20489B ENU TrainerHandbook

MCT USE ONLY.
STUDENT USE PROHIBITED

O F F I C I A L M I C R O S O F T L E A R N I N G P R O D U C T
20489B
Developing Microsoft® SharePoint® Server
2013 Advanced Solutions
MCT USE ONLY. STUDENT USE PROHIBITED
ii Developing Microsoft SharePoint Server 2013 Advanced Solutions
Information in this document, including URL and other Internet Web site references, is subject to change
without notice. Unless otherwise noted, the example companies, organizations, products, domain names,
e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with
any real company, organization, product, domain name, e-mail address, logo, person, place or event is
intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the
user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in
or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical,
photocopying, recording, or otherwise), or for any purpose, without the express written permission of
Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property
rights covering subject matter in this document. Except as expressly provided in any written license
agreement from Microsoft, the furnishing of this document does not give you any license to these
patents, trademarks, copyrights, or other intellectual property.
The names of manufacturers, products, or URLs are provided for informational purposes only and
Microsoft makes no representations and warranties, either expressed, implied, or statutory, regarding
these manufacturers or the use of the products with any Microsoft technologies. The inclusion of a
manufacturer or product does not imply endorsement of Microsoft of the manufacturer or product. Links
may be provided to third party sites. Such sites are not under the control of Microsoft and Microsoft is not
responsible for the contents of any linked site or any link contained in a linked site, or any changes or
updates to such sites. Microsoft is not responsible for webcasting or any other form of transmission
received from any linked site. Microsoft is providing these links to you only as a convenience, and the
inclusion of any link does not imply endorsement of Microsoft of the site or the products contained
therein.
© 2013 Microsoft Corporation. All rights reserved.
Microsoft and the trademarks listed at

http://www.microsoft.com/about/legal/en/us/IntellectualProperty/Trademarks/EN-US.aspx are trademarks of
the Microsoft group of companies. All other trademarks are property of their respective owners
Product Number: 20489B
Released: 11/2013
MICROSOFT LICENSE TERMS
MICROSOFT INSTRUCTOR-LED COURSEWARE
These license terms are an agreement between Microsoft Corporation (or based on where you live, one of its
affiliates) and you. Please read them. They apply to your use of the content accompanying this agreement which
includes the media on which you received it, if any. These license terms also apply to Trainer Content and any
updates and supplements for the Licensed Content unless other terms accompany those items. If so, those terms
apply.
BY ACCESSING, DOWNLOADING OR USING THE LICENSED CONTENT, YOU ACCEPT THESE TERMS.
IF YOU DO NOT ACCEPT THEM, DO NOT ACCESS, DOWNLOAD OR USE THE LICENSED CONTENT.
If you comply with these license terms, you have the rights below for each license you acquire.
1. DEFINITIONS.
a. “Authorized Learning Center” means a Microsoft IT Academy Program Member, Microsoft Learning
Competency Member, or such other entity as Microsoft may designate from time to time.
b. “Authorized Training Session” means the instructor-led training class using Microsoft Instructor-Led
Courseware conducted by a Trainer at or through an Authorized Learning Center.
c. “Classroom Device” means one (1) dedicated, secure computer that an Authorized Learning Center owns
or controls that is located at an Authorized Learning Center’s training facilities that meets or exceeds the
hardware level specified for the particular Microsoft Instructor-Led Courseware.
d. “End User” means an individual who is (i) duly enrolled in and attending an Authorized Training Session
or Private Training Session, (ii) an employee of a MPN Member, or (iii) a Microsoft full-time employee.
e. “Licensed Content” means the content accompanying this agreement which may include the Microsoft
Instructor-Led Courseware or Trainer Content.
f. “Microsoft Certified Trainer” or “MCT” means an individual who is (i) engaged to teach a training session
to End Users on behalf of an Authorized Learning Center or MPN Member, and (ii) currently certified as a
Microsoft Certified Trainer under the Microsoft Certification Program.
g. “Microsoft Instructor-Led Courseware” means the Microsoft-branded instructor-led training course that
educates IT professionals and developers on Microsoft technologies. A Microsoft Instructor-Led
Courseware title may be branded as MOC, Microsoft Dynamics or Microsoft Business Group courseware.
h. “Microsoft IT Academy Program Member” means an active member of the Microsoft IT Academy
Program.
i. “Microsoft Learning Competency Member” means an active member of the Microsoft Partner Network
program in good standing that currently holds the Learning Competency status.
j. “MOC” means the “Official Microsoft Learning Product” instructor-led courseware known as Microsoft
Official Course that educates IT professionals and developers on Microsoft technologies.
k. “MPN Member” means an active silver or gold-level Microsoft Partner Network program member in good
standing.
l. “Personal Device” means one (1) personal computer, device, workstation or other digital electronic device
that you personally own or control that meets or exceeds the hardware level specified for the particular
Microsoft Instructor-Led Courseware.
m. “Private Training Session” means the instructor-led training classes provided by MPN Members for
corporate customers to teach a predefined learning objective using Microsoft Instructor-Led Courseware.
These classes are not advertised or promoted to the general public and class attendance is restricted to
individuals employed by or contracted by the corporate customer.
n. “Trainer” means (i) an academically accredited educator engaged by a Microsoft IT Academy Program
Member to teach an Authorized Training Session, and/or (ii) a MCT.
o. “Trainer Content” means the trainer version of the Microsoft Instructor-Led Courseware and additional
supplemental content designated solely for Trainers’ use to teach a training session using the Microsoft
Instructor-Led Courseware. Trainer Content may include Microsoft PowerPoint presentations, trainer
preparation guide, train the trainer materials, Microsoft One Note packs, classroom setup guide and Pre-
release course feedback form. To clarify, Trainer Content does not include any software, virtual hard
disks or virtual machines.
2. USE RIGHTS. The Licensed Content is licensed not sold. The Licensed Content is licensed on a one copy
per user basis, such that you must acquire a license for each individual that accesses or uses the Licensed
Content.
2.1 Below are five separate sets of use rights. Only one set of rights apply to you.
a. If you are a Microsoft IT Academy Program Member:

i. Each license acquired on behalf of yourself may only be used to review one (1) copy of the Microsoft
Instructor-Led Courseware in the form provided to you. If the Microsoft Instructor-Led Courseware is
in digital format, you may install one (1) copy on up to three (3) Personal Devices. You may not
install the Microsoft Instructor-Led Courseware on a device you do not own or control.
ii. For each license you acquire on behalf of an End User or Trainer, you may either:
1. distribute one (1) hard copy version of the Microsoft Instructor-Led Courseware to one (1) End
User who is enrolled in the Authorized Training Session, and only immediately prior to the
commencement of the Authorized Training Session that is the subject matter of the Microsoft
Instructor-Led Courseware being provided, or
2. provide one (1) End User with the unique redemption code and instructions on how they can
access one (1) digital version of the Microsoft Instructor-Led Courseware, or
3. provide one (1) Trainer with the unique redemption code and instructions on how they can
access one (1) Trainer Content,
provided you comply with the following:
iii. you will only provide access to the Licensed Content to those individuals who have acquired a valid
license to the Licensed Content,
iv. you will ensure each End User attending an Authorized Training Session has their own valid licensed
copy of the Microsoft Instructor-Led Courseware that is the subject of the Authorized Training
Session,
v. you will ensure that each End User provided with the hard-copy version of the Microsoft Instructor-
Led Courseware will be presented with a copy of this agreement and each End User will agree that
their use of the Microsoft Instructor-Led Courseware will be subject to the terms in this agreement
prior to providing them with the Microsoft Instructor-Led Courseware. Each individual will be required
to denote their acceptance of this agreement in a manner that is enforceable under local law prior to
their accessing the Microsoft Instructor-Led Courseware,
vi. you will ensure that each Trainer teaching an Authorized Training Session has their own valid
licensed copy of the Trainer Content that is the subject of the Authorized Training Session,
vii. you will only use qualified Trainers who have in-depth knowledge of and experience with the
Microsoft technology that is the subject of the Microsoft Instructor-Led Courseware being taught for
all your Authorized Training Sessions,
viii. you will only deliver a maximum of 15 hours of training per week for each Authorized Training
Session that uses a MOC title, and
ix. you acknowledge that Trainers that are not MCTs will not have access to all of the trainer resources
for the Microsoft Instructor-Led Courseware.
b. If you are a Microsoft Learning Competency Member:

User attending the Authorized Training Session and only immediately prior to the
commencement of the Authorized Training Session that is the subject matter of the Microsoft
Instructor-Led Courseware provided, or
2. provide one (1) End User attending the Authorized Training Session with the unique redemption
code and instructions on how they can access one (1) digital version of the Microsoft Instructor-
Led Courseware, or
3. you will provide one (1) Trainer with the unique redemption code and instructions on how they
can access one (1) Trainer Content,
iv. you will ensure that each End User attending an Authorized Training Session has their own valid
licensed copy of the Microsoft Instructor-Led Courseware that is the subject of the Authorized
Training Session,
v. you will ensure that each End User provided with a hard-copy version of the Microsoft Instructor-Led
Courseware will be presented with a copy of this agreement and each End User will agree that their
use of the Microsoft Instructor-Led Courseware will be subject to the terms in this agreement prior to
providing them with the Microsoft Instructor-Led Courseware. Each individual will be required to
denote their acceptance of this agreement in a manner that is enforceable under local law prior to
vi. you will ensure that each Trainer teaching an Authorized Training Session has their own valid
licensed copy of the Trainer Content that is the subject of the Authorized Training Session,
vii. you will only use qualified Trainers who hold the applicable Microsoft Certification credential that is
the subject of the Microsoft Instructor-Led Courseware being taught for your Authorized Training
Sessions,
viii. you will only use qualified MCTs who also hold the applicable Microsoft Certification credential that is
the subject of the MOC title being taught for all your Authorized Training Sessions using MOC,
ix. you will only provide access to the Microsoft Instructor-Led Courseware to End Users, and
x. you will only provide access to the Trainer Content to Trainers.
c. If you are a MPN Member:
User attending the Private Training Session, and only immediately prior to the commencement
of the Private Training Session that is the subject matter of the Microsoft Instructor-Led
Courseware being provided, or
2. provide one (1) End User who is attending the Private Training Session with the unique
redemption code and instructions on how they can access one (1) digital version of the
Microsoft Instructor-Led Courseware, or
3. you will provide one (1) Trainer who is teaching the Private Training Session with the unique
redemption code and instructions on how they can access one (1) Trainer Content,
iv. you will ensure that each End User attending an Private Training Session has their own valid licensed
copy of the Microsoft Instructor-Led Courseware that is the subject of the Private Training Session,
v. you will ensure that each End User provided with a hard copy version of the Microsoft Instructor-Led
Courseware will be presented with a copy of this agreement and each End User will agree that their
use of the Microsoft Instructor-Led Courseware will be subject to the terms in this agreement prior to
providing them with the Microsoft Instructor-Led Courseware. Each individual will be required to
denote their acceptance of this agreement in a manner that is enforceable under local law prior to
vi. you will ensure that each Trainer teaching an Private Training Session has their own valid licensed
copy of the Trainer Content that is the subject of the Private Training Session,
vii. you will only use qualified Trainers who hold the applicable Microsoft Certification credential that is
the subject of the Microsoft Instructor-Led Courseware being taught for all your Private Training
Sessions,
viii. you will only use qualified MCTs who hold the applicable Microsoft Certification credential that is the
subject of the MOC title being taught for all your Private Training Sessions using MOC,
ix. you will only provide access to the Microsoft Instructor-Led Courseware to End Users, and
x. you will only provide access to the Trainer Content to Trainers.
d. If you are an End User:

For each license you acquire, you may use the Microsoft Instructor-Led Courseware solely for your
personal training use. If the Microsoft Instructor-Led Courseware is in digital format, you may access the
Microsoft Instructor-Led Courseware online using the unique redemption code provided to you by the
training provider and install and use one (1) copy of the Microsoft Instructor-Led Courseware on up to
three (3) Personal Devices. You may also print one (1) copy of the Microsoft Instructor-Led Courseware.
You may not install the Microsoft Instructor-Led Courseware on a device you do not own or control.
e. If you are a Trainer.

i. For each license you acquire, you may install and use one (1) copy of the Trainer Content in the
form provided to you on one (1) Personal Device solely to prepare and deliver an Authorized
Training Session or Private Training Session, and install one (1) additional copy on another Personal
Device as a backup copy, which may be used only to reinstall the Trainer Content. You may not
install or use a copy of the Trainer Content on a device you do not own or control. You may also
print one (1) copy of the Trainer Content solely to prepare for and deliver an Authorized Training
Session or Private Training Session.
ii. You may customize the written portions of the Trainer Content that are logically associated with
instruction of a training session in accordance with the most recent version of the MCT agreement.
If you elect to exercise the foregoing rights, you agree to comply with the following: (i)
customizations may only be used for teaching Authorized Training Sessions and Private Training
Sessions, and (ii) all customizations will comply with this agreement. For clarity, any use of
“customize” refers only to changing the order of slides and content, and/or not using all the slides or
content, it does not mean changing or modifying any slide or content.
2.2 Separation of Components. The Licensed Content is licensed as a single unit and you may not
separate their components and install them on different devices.
2.3 Redistribution of Licensed Content. Except as expressly provided in the use rights above, you may
not distribute any Licensed Content or any portion thereof (including any permitted modifications) to any
third parties without the express written permission of Microsoft.
2.4 Third Party Programs and Services. The Licensed Content may contain third party programs or
services. These license terms will apply to your use of those third party programs or services, unless other
terms accompany those programs and services.
2.5 Additional Terms. Some Licensed Content may contain components with additional terms,
conditions, and licenses regarding its use. Any non-conflicting terms in those conditions and licenses also
apply to your use of that respective component and supplements the terms described in this agreement.
3. LICENSED CONTENT BASED ON PRE-RELEASE TECHNOLOGY. If the Licensed Content’s subject

matter is based on a pre-release version of Microsoft technology (“Pre-release”), then in addition to the
other provisions in this agreement, these terms also apply:
a. Pre-Release Licensed Content. This Licensed Content subject matter is on the Pre-release version of
the Microsoft technology. The technology may not work the way a final version of the technology will
and we may change the technology for the final version. We also may not release a final version.
Licensed Content based on the final version of the technology may not contain the same information as
the Licensed Content based on the Pre-release version. Microsoft is under no obligation to provide you
with any further content, including any Licensed Content based on the final version of the technology.
b. Feedback. If you agree to give feedback about the Licensed Content to Microsoft, either directly or
through its third party designee, you give to Microsoft without charge, the right to use, share and
commercialize your feedback in any way and for any purpose. You also give to third parties, without
charge, any patent rights needed for their products, technologies and services to use or interface with
any specific parts of a Microsoft software, Microsoft product, or service that includes the feedback. You
will not give feedback that is subject to a license that requires Microsoft to license its software,
technologies, or products to third parties because we include your feedback in them. These rights
survive this agreement.
c. Pre-release Term. If you are an Microsoft IT Academy Program Member, Microsoft Learning
Competency Member, MPN Member or Trainer, you will cease using all copies of the Licensed Content on
the Pre-release technology upon (i) the date which Microsoft informs you is the end date for using the
Licensed Content on the Pre-release technology, or (ii) sixty (60) days after the commercial release of the
technology that is the subject of the Licensed Content, whichever is earliest (“Pre-release term”).
Upon expiration or termination of the Pre-release term, you will irretrievably delete and destroy all copies
of the Licensed Content in your possession or under your control.
4. SCOPE OF LICENSE. The Licensed Content is licensed, not sold. This agreement only gives you some
rights to use the Licensed Content. Microsoft reserves all other rights. Unless applicable law gives you more
rights despite this limitation, you may use the Licensed Content only as expressly permitted in this
agreement. In doing so, you must comply with any technical limitations in the Licensed Content that only
allows you to use it in certain ways. Except as expressly permitted in this agreement, you may not:
 access or allow any individual to access the Licensed Content if they have not acquired a valid license
for the Licensed Content,
 alter, remove or obscure any copyright or other protective notices (including watermarks), branding
or identifications contained in the Licensed Content,
 modify or create a derivative work of any Licensed Content,
 publicly display, or make the Licensed Content available for others to access or use,
 copy, print, install, sell, publish, transmit, lend, adapt, reuse, link to or post, make available or
distribute the Licensed Content to any third party,
 work around any technical limitations in the Licensed Content, or
 reverse engineer, decompile, remove or otherwise thwart any protections or disassemble the
Licensed Content except and only to the extent that applicable law expressly permits, despite this
limitation.
5. RESERVATION OF RIGHTS AND OWNERSHIP. Microsoft reserves all rights not expressly granted to
you in this agreement. The Licensed Content is protected by copyright and other intellectual property laws
and treaties. Microsoft or its suppliers own the title, copyright, and other intellectual property rights in the
Licensed Content.
6. EXPORT RESTRICTIONS. The Licensed Content is subject to United States export laws and regulations.
You must comply with all domestic and international export laws and regulations that apply to the Licensed
Content. These laws include restrictions on destinations, end users and end use. For additional information,
see www.microsoft.com/exporting.
7. SUPPORT SERVICES. Because the Licensed Content is “as is”, we may not provide support services for it.
8. TERMINATION. Without prejudice to any other rights, Microsoft may terminate this agreement if you fail
to comply with the terms and conditions of this agreement. Upon termination of this agreement for any
reason, you will immediately stop all use of and delete and destroy all copies of the Licensed Content in
your possession or under your control.
9. LINKS TO THIRD PARTY SITES. You may link to third party sites through the use of the Licensed
Content. The third party sites are not under the control of Microsoft, and Microsoft is not responsible for
the contents of any third party sites, any links contained in third party sites, or any changes or updates to
third party sites. Microsoft is not responsible for webcasting or any other form of transmission received
from any third party sites. Microsoft is providing these links to third party sites to you only as a
convenience, and the inclusion of any link does not imply an endorsement by Microsoft of the third party
site.
10. ENTIRE AGREEMENT. This agreement, and any additional terms for the Trainer Content, updates and
supplements are the entire agreement for the Licensed Content, updates and supplements.
11. APPLICABLE LAW.

a. United States. If you acquired the Licensed Content in the United States, Washington state law governs
the interpretation of this agreement and applies to claims for breach of it, regardless of conflict of laws
principles. The laws of the state where you live govern all other claims, including claims under state
consumer protection laws, unfair competition laws, and in tort.
b. Outside the United States. If you acquired the Licensed Content in any other country, the laws of that
country apply.
12. LEGAL EFFECT. This agreement describes certain legal rights. You may have other rights under the laws
of your country. You may also have rights with respect to the party from whom you acquired the Licensed
Content. This agreement does not change your rights under the laws of your country if the laws of your
country do not permit it to do so.
13. DISCLAIMER OF WARRANTY. THE LICENSED CONTENT IS LICENSED "AS-IS" AND "AS
AVAILABLE." YOU BEAR THE RISK OF USING IT. MICROSOFT AND ITS RESPECTIVE
AFFILIATES GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. YOU MAY
HAVE ADDITIONAL CONSUMER RIGHTS UNDER YOUR LOCAL LAWS WHICH THIS AGREEMENT
CANNOT CHANGE. TO THE EXTENT PERMITTED UNDER YOUR LOCAL LAWS, MICROSOFT AND
ITS RESPECTIVE AFFILIATES EXCLUDES ANY IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
14. LIMITATION ON AND EXCLUSION OF REMEDIES AND DAMAGES. YOU CAN RECOVER FROM
MICROSOFT, ITS RESPECTIVE AFFILIATES AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP
TO US$5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL,
LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES.
This limitation applies to

o anything related to the Licensed Content, services, content (including code) on third party Internet
sites or third-party programs; and
o claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence,
or other tort to the extent permitted by applicable law.
It also applies even if Microsoft knew or should have known about the possibility of the damages. The
above limitation or exclusion may not apply to you because your country may not allow the exclusion or
limitation of incidental, consequential or other damages.
Please note: As this Licensed Content is distributed in Quebec, Canada, some of the clauses in this
agreement are provided below in French.
Remarque : Ce le contenu sous licence étant distribué au Québec, Canada, certaines des clauses
dans ce contrat sont fournies ci-dessous en français.
EXONÉRATION DE GARANTIE. Le contenu sous licence visé par une licence est offert « tel quel ». Toute
utilisation de ce contenu sous licence est à votre seule risque et péril. Microsoft n’accorde aucune autre garantie
expresse. Vous pouvez bénéficier de droits additionnels en vertu du droit local sur la protection dues
consommateurs, que ce contrat ne peut modifier. La ou elles sont permises par le droit locale, les garanties
implicites de qualité marchande, d’adéquation à un usage particulier et d’absence de contrefaçon sont exclues.
LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES

DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une indemnisation en cas de dommages
directs uniquement à hauteur de 5,00 $ US. Vous ne pouvez prétendre à aucune indemnisation pour les autres
dommages, y compris les dommages spéciaux, indirects ou accessoires et pertes de bénéfices.
Cette limitation concerne:
 tout ce qui est relié au le contenu sous licence, aux services ou au contenu (y compris le code)
figurant sur des sites Internet tiers ou dans des programmes tiers; et.
 les réclamations au titre de violation de contrat ou de garantie, ou au titre de responsabilité
stricte, de négligence ou d’une autre faute dans la limite autorisée par la loi en vigueur.
Elle s’applique également, même si Microsoft connaissait ou devrait connaître l’éventualité d’un tel dommage. Si
votre pays n’autorise pas l’exclusion ou la limitation de responsabilité pour les dommages indirects, accessoires
ou de quelque nature que ce soit, il se peut que la limitation ou l’exclusion ci-dessus ne s’appliquera pas à votre
égard.
EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. Vous pourriez avoir d’autres droits
prévus par les lois de votre pays. Le présent contrat ne modifie pas les droits que vous confèrent les lois de votre
pays si celles-ci ne le permettent pas.
Revised September 2012

x Developing Microsoft SharePoint Server 2013 Advanced Solutions
Developing Microsoft SharePoint Server 2013 Advanced Solutions xi
Acknowledgments
Microsoft Learning wants to acknowledge and thank the following for their contribution toward
developing this title. Their effort at various stages in the development has ensured that you have a good
classroom experience.
Paul Barnes – Content Developer

Paul Barnes is a Graduate Technologist with Content Master where he has been working with Microsoft
products and technologies, specializing in Microsoft Visual C#. Paul holds a BSc in computing and is
currently working towards MCSD certification.
Chris Beckett – Content Developer

Chris Beckett is an Information Systems Architect, Consultant, Author and Trainer. He has over 23 years of
experience leading the development of enterprise business solutions, and has been a dedicated
SharePoint technology specialist since 2003. His areas of expertise include Enterprise Content
Management, Business Process Automation, and Enterprise Search. Chris has a B.Sc. in Computer
Information Systems, and is Microsoft Certified in SharePoint administration and development for 2007,
2010 and 2013. You can read Chris’s blog at blog.sharepointbits.com, or follow him on Twitter
@sharepointbits.
Chris Givens – Content Developer

Chris Givens, SharePoint MVP, MCT, CISSP, CCNP is a SharePoint architect, author, trainer and consultant.
He is the CEO of Architecting Connected Systems, a top Microsoft courseware provider, with several
popular courseware titles in SharePoint with customers in over 40 countries around the world. Originally
from Oklahoma, and after 10 years in Seattle working in several startups, Chris now lives in San Diego with
his lovely wife Lidiya and his son Igor.
Scot Hillier – Technical Reviewer

Scot Hillier is an independent consultant and Microsoft SharePoint Most Valuable Professional (MVP)
focused on creating solutions for Information Workers with SharePoint, Office, and related technologies.
He is the author/coauthor of 18 books on Microsoft technologies including “Inside SharePoint 2013” and
“App Development in SharePoint 2013”. Scot splits his time between consulting on SharePoint projects,
speaking at SharePoint events like the Microsoft SharePoint Conference, and delivering training for
SharePoint developers through Critical Path Training. Scot is a former U. S. Navy submarine officer and
graduate of the Virginia Military Institute. He can be reached at scot@scothillier.net.
Jason Lee – Content Developer

Jason Lee is a Principal Technologist with Content Master where he has been working with Microsoft
products and technologies for several years, specializing in SharePoint development and architecture.
Jason holds a PhD in computing and is currently MCPD and MCTS certified. You can read Jason's technical
blog at www.jrjlee.com.
Alistair Matthews – Content Developer

Alistair Matthews is the Principal Consultant for Web Dojo Ltd., a UK consultancy company specializing in
Microsoft Technologies. Alistair concentrates on SharePoint and ASP.NET and has extensive experience of
other Microsoft products including SQL Server, Windows Azure, and the .NET Framework, which he has
gained over a 15 year career. Alistair holds an MA in Natural Sciences from Cambridge University and lives
the telecommuting dream in Cornwall, UK.
xii Developing Microsoft SharePoint Server 2013 Advanced Solutions
Telmo Sampaio – Content Developer

Telmo Sampaio is the Chief Geek at MCTrainer.NET and TechKnowLogical in Miami, FL specializing in
System Center, SharePoint, SQL and .NET. He is a trainer, consultant, author and speaker at events such as
TechEd, MMS, and PASS. To date, he has been certified in over 20 different Microsoft products, passing
over 80 exams, and helped Microsoft build courseware and certification exams. He is an MCT Regional
Lead for the US, and the president for IAMCT in North America.
Mike Sumsion – Content Developer

Mike Sumsion is a Senior Technologist with Content Master, where he has worked with a range of
Microsoft technologies. Mike has worked with SharePoint products since Microsoft Office SharePoint
Server 2007, and has produced a variety of courseware, hands-on-labs, and other documentation. Michael
has an honors degree in Computer Science, and is currently MCTS certified. You can read Mike's blog at
www.mikesumsion.com.
Developing Microsoft SharePoint Server 2013 Advanced Solutions xiii
Contents
Module 1: Creating Robust and Efficient Apps for SharePoint
Lesson 1: Apps for SharePoint 1-2
Lesson 2: Communicating with SharePoint from an App 1-9
Lesson 3: Authenticating and Authorizing Apps for SharePoint 1-21
Lesson 4: Designing Apps for Performance 1-32
Lab: Monitoring SharePoint Health Scores 1-37
Module 2: Developing Managed Metadata Solutions

Lesson 1: Understanding Managed Metadata 2-2
Lesson 2: Configuring Managed Metadata Term Sets 2-9
Lab A: Developing Managed Metadata Solutions (Part 1) 2-19
Lesson 3: Working with Managed Metadata Fields 2-26
Lab B: Developing Managed Metadata Solutions (Part 2) 2-32
Module 3: Interacting with the Search Service

Lesson 1: Understanding the SharePoint 2013 Search Service 3-2
Lesson 2: Building Search Queries with KQL and FQL 3-13
Lesson 3: Executing Search Queries from Code 3-18
Lab: Executing Search Queries from SharePoint Apps 3-26
Module 4: Customizing the Search Experience

Lesson 1: Customizing Query Processing 4-2
Lesson 2: Customizing Search Results 4-16
Lab A: Configuring Result Types and Display Templates 4-27
Lesson 3: Customizing Content Processing 4-30
Lab B: Configuring Entity Extraction 4-38
Module 5: Implementing Enterprise Content Management

Lesson 1: Working with eDiscovery 5-2
Lesson 2: Working with Content Management 5-11
Lesson 3: Automating Records Management 5-18
Lab: Implementing Content Management Functionality 5-25
Module 6: Developing a Publishing Site for Web Content

Lesson 1: Programming with the Web Content Publishing API 6-2
Lesson 2: Developing Page Components for Web Content Publishing 6-10
Lab: Customizing a SharePoint Publishing Site 6-27
xiv Developing Microsoft SharePoint Server 2013 Advanced Solutions
Module 7: Structuring and Publishing Websites for All Users

Lesson 1: Website Structure and Navigation 7-2
Lesson 2: Publishing Content 7-11
Lab A: Structuring a SharePoint Publishing Site 7-17
Lesson 3: Publishing to Mobile Devices 7-23
Lesson 4: Multi-Language Sites Using Variations 7-27
Lab B: Publishing for Multiple Devices and Languages 7-33
Module 8: Developing Optimized Internet Sites

Lesson 1: Optimizing a SharePoint Site for Search Engines 8-2
Lesson 2: Optimizing Performance and Scalability 8-12
Lab: Optimizing SharePoint Publishing Sites 8-23
Module 9: Working with Business Connectivity Services

Lesson 1: Business Connectivity Services in SharePoint 2013 9-2
Lesson 2: Creating BDC Models in SharePoint Designer 9-11
Lesson 3: Creating BDC Models in Visual Studio 2012 9-23
Lab: Working with Business Connectivity Services 9-30
Module 10: Creating Advanced Business Data Connectivity Models

Lesson 1: Configuring BDC Models for Search 10-2
Lesson 2: Developing Custom Connectivity Components 10-9
Lesson 3: Working with External Events and Notifications 10-16
Lab: Creating and Deploying a .NET Connectivity Assembly 10-30
Module 11: Working with Business Data

Lesson 1: Working with Business Data in Composite Solutions 11-2
Lesson 2: Working with Business Data in Custom Solutions 11-12
Lesson 3: Working with Business Data in Client Applications 11-26
Lab: Working with Business Data in Apps for SharePoint 11-36
Module 12: Managing and Accessing User Profile Data

Lesson 1: User Profile Data in SharePoint 2013 12-2
Lesson 2: Options for Accessing User Profile Data 12-6
Lesson 3: Managing User Profile Data 12-9
Lab A: Accessing User Profile Data 12-15
Lesson 4: Managing User Profile Properties 12-20
Lab B: Managing User Profile Properties 12-25
Module 13: Customizing the Social Workload

Lesson 1: Overview of the Social Workload 13-2
Lesson 2: Developing Social Solutions 13-5
Lesson 3: Working with Feeds 13-15
Developing Microsoft SharePoint Server 2013 Advanced Solutions xv
Lab: Creating a Social App Part 13-23
Module 14: Monitoring and Troubleshooting Custom SharePoint Solutions

Lesson 1: Debugging SharePoint Apps in Visual Studio 14-2
Lesson 2: Diagnosing Faults in Deployed Apps 14-9
Lesson 3: Testing Performance and Scalability 14-15
Lab: Enabling ASP.NET Tracing 14-22
Lab Answer Keys

Module 1 Lab: Monitoring SharePoint Health Scores L1-1
Module 2 Lab A: Developing Managed Metadata Solutions (Part 1) L2-1
Module 2 Lab B: Developing Managed Metadata Solutions (Part 2) L2-10
Module 3 Lab: Executing Search Queries from SharePoint Apps L3-1
Module 4 Lab A: Configuring Result Types and Display Templates L4-1
Module 4 Lab B: Configuring Entity Extraction L4-5
Module 5 Lab: Implementing Content Management Functionality L5-1
Module 6 Lab: Customizing a SharePoint Publishing Site L6-1
Module 7 Lab A: Structuring a SharePoint Publishing Site L7-1
Module 7 Lab B: Publishing Sites for Multiple Devices L7-7
Module 8 Lab: Optimizing SharePoint Publishing Sites L8-1
Module 9 Lab: Working with Business Connectivity Services L9-1
Module 10 Lab: Creating and Deploying a .NET Connectivity Assembly L10-1
Module 11 Lab: Working with Business Data in Apps for SharePoint L11-1
Module 12 Lab A: Accessing User Profile Data L12-1
Module 12 Lab B: Managing User Profile Properties L12-5
Module 13 Lab: Creating a Social App Part L13-1
Module 14 Lab: Enabling ASP.NET Tracing L14-1
About This Course i
About This Course

This section provides a brief description of the course, audience, suggested prerequisites, and course
objectives.
Course Description
This course teaches students how to apply their core SharePoint development skills to more advanced
SharePoint development projects. Students learn how to develop solutions and apps that interact with the
key SharePoint 2013 workloads, including the search service, enterprise content management
functionality, Business Connectivity Services, social functionality and user profiles, and web content
management features. Students also learn more advanced SharePoint development techniques such as
how to optimize SharePoint code and how to monitor and troubleshoot custom SharePoint components.
Audience
This course is intended for professional developers who develop solutions for SharePoint products and
technologies in a team-based, medium-sized to large development environment. The course is ideally
suited to SharePoint developers who have gained some experience with SharePoint 2013 and who are
looking to build on their existing skills.
The ideal candidate is a technical lead with at least four two years of SharePoint and web development
experience. The candidate is responsible for designing custom code for projects that are deployed to or
interact with SharePoint environments. This includes:
 Selecting an appropriate approach and building customizations in SharePoint.

 Creating and implementing a strategy for solution packaging, deployment, and upgrading.
 Identifying SharePoint data and content structures for customizations.
 Performing diagnostics and debugging.

 Planning and designing applications for scalability and performance.
 Identifying and mitigating performance issues of customizations.
 Understanding authentication and authorization.
 Experience with Windows PowerShell.
 Broad familiarity with SharePoint capabilities.
 Familiarity with Online Services such as Azure and SharePoint Online.
Student Prerequisites
This course requires that you meet the following prerequisites:
 Completion of course 20488 or equivalent technical knowledge.
 A basic understanding of how to create, deploy, and manage apps for SharePoint.
 A working knowledge of using Visual Studio 2010 or Visual Studio 2012 to develop solutions.
 A basic working knowledge of SharePoint solution development, either in SharePoint 2013 or in

earlier versions of SharePoint.
 A working knowledge of Visual C# and the .NET Framework 4.5.

About This Course ii
 A basic understanding of ASP.NET and server-side web development technologies, including

request/response and the page lifecycle.
 A basic understanding of AJAX and asynchronous programming techniques.
 A basic working knowledge of client-side web technologies including HTML, CSS, and JavaScript.
 Familiarity with approaches to authentication and authorization, including claims-based

authentication.
Course Objectives
After completing this course, students will be able to:
 Develop robust and efficient apps for SharePoint.
 Build solutions and apps that leverage Managed Metadata Service functionality.
 Build and execute search queries from client-side and server-side code.
 Customize how search queries are processed and how search results are presented.
 Configure records management and e-discovery solutions.
 Develop components for publishing sites.
 Develop websites for multiple languages and multiple devices.
 Optimize internet sites for search and performance.

 Create Business Data Connectivity (BDC) models.
 Create advanced BDS models and custom connectors.
 Interact with Business Connectivity Services (BCS) data from custom SharePoint solutions.
 Configure user profile properties and interact with user profile data.
 Interact with social functionality from custom SharePoint solutions.
 Monitor and troubleshoot custom SharePoint solutions.
Course Outline
The course outline is as follows:
Module 1, "Creating Robust and Efficient Apps for SharePoint"
Module 2, "Developing Managed Metadata Solutions"
Module 3, "Interacting with the Search Service"
Module 4, "Customizing the Search Experience"
Module 5, "Implementing Enterprise Content Management"
Module 6, "Developing a Publishing Site for Web Content"
Module 7, "Structuring and Publishing Websites for All Users"
Module 8, "Developing Optimized Internet Sites"
Module 9, "Working with Business Connectivity Services"

Module 10, "Creating Advanced Business Data Connectivity Models"
About This Course iii
Module 11, "Working with Business Data"
Module 12, "Managing and Accessing User Profile Data"
Module 13, "Customizing the Social Workload"
Module 14, "Monitoring and Troubleshooting Custom SharePoint Solutions"
Course Materials
The following materials are included with your kit:
 Course Handbook: a succinct classroom learning guide that provides the critical technical
information in a crisp, tightly-focused format, which is essential for an effective in-class learning
experience.
 Lessons: guide you through the learning objectives and provide the key points that are critical to
the success of the in-class learning experience.
 Labs: provide a real-world, hands-on platform for you to apply the knowledge and skills learned
in the module.
 Module Reviews and Takeaways: provide on-the-job reference material to boost knowledge
and skills retention.
 Lab Answer Keys: provide step-by-step lab solution guidance.
Course Companion Content: searchable, easy-to-browse digital content with integrated premium
online resources that supplement the Course Handbook.
 Modules: include companion content, such as questions and answers, detailed demo steps and
additional reading links, for each lesson. Additionally, they include Lab Review questions and
answers and Module Reviews and Takeaways sections, which contain the review questions and
answers, best practices, common issues and troubleshooting tips with answers, and real-world
issues and scenarios with answers.
 Resources: include well-categorized additional resources that give you immediate access to the
most current premium content on TechNet, MSDN®, or Microsoft® Press®.
Student Course files: includes the Allfiles.exe, a self-extracting executable file that contains all
required files for the labs and demonstrations.
Note: For this version of the Courseware, the Allfiles.exe file is not available. However, this file will be
published when the next (B) version of this course is released, and students who have taken this
course will be able to download the Allfiles.exe at that time from the
http://www.microsoft.com/learning/companionmoc site.
 Course evaluation: at the end of the course, you will have the opportunity to complete an online
evaluation to provide feedback on the course, training facility, and instructor.
 To provide additional comments or feedback on the course, send an email to

support@mscourseware.com. To inquire about the Microsoft Certification Program, send an
email to mcphelp@microsoft.com.
About This Course iv
Virtual Machine Environment

This section provides the information for setting up the classroom environment to support the business
scenario of the course.
Virtual Machine Configuration

In this course, you will use Microsoft® Hyper-V™ to perform the labs.
Important: At the end of each lab, you must revert the virtual machines to a snapshot.
You can find the instructions for this procedure at the end of each lab
The following table shows the role of each virtual machine that is used in this course:
Virtual machine Role

20489B-LON-SP-xx (where xx Domain controller, database server, and
is the module number) SharePoint development environment.
Software Configuration
The following software is installed on each VM:
 SQL Server 2012 SP1, with the following features installed:
 Database Engine Services
 Full-Text and Semantic Extractions for Search

 Management Tools – Complete
 SharePoint Server 2013, Enterprise Edition
 Workflow Manager 1.0
 Office 2013 Professional Plus
 Visio 2013
 SharePoint Designer 2013

 Visual Studio 2012 Premium Edition with Update 1
 Office Developer Tools for Visual Studio 2012
Course Files
The files associated with the labs in this course are located in the E:\Labfiles folder on the student
computers.
Classroom Setup
Each classroom computer will have the same virtual machine configured in the same way.
Course Hardware Level

To ensure a satisfactory student experience, Microsoft Learning requires a minimum equipment
configuration for trainer and student computers in all Microsoft Certified Partner for Learning Solutions
(CPLS) classrooms in which Official Microsoft Learning Product courseware is taught.
About This Course v
Hardware Level 7
 64 bit Intel Virtualization Technology (Intel VT) or AMD Virtualization (AMD-V) processor (2.8 GHz
dual core or better recommended)
 Dual 500 GB hard disks 7200 RPM SATA or faster (striped)
 16GB RAM
 DVD drive (dual layer recommended)
 Network adapter
 Sound card
 Dual SVGA 17-inch or larger monitors supporting 1440x900 minimum resolution
 Microsoft Mouse or compatible pointing device
In addition, the instructor computer must be connected to a projection display device that supports SVGA
1024 x 768 pixels, 16 bit colors.
At this minimum specification, students may experience some delays when completing tasks on the virtual
machine. You can achieve the biggest improvements in performance by running the virtual machine on
solid-state drives (SSDs).
1-1
Module 1
Creating Robust and Efficient Apps for SharePoint
Contents:
Module Overview 1-1
Lesson 1: Apps for SharePoint 1-2
Lesson 2: Communicating with SharePoint from an App 1-9
Lesson 3: Authenticating and Authorizing Apps for SharePoint 1-21
Lesson 4: Designing Apps for Performance 1-32
Lab: Monitoring SharePoint Health Scores 1-37
Module Review and Takeaways 1-43
Module Overview
Apps for Microsoft® SharePoint® provide a completely new way of developing and distributing custom
functionality for Microsoft SharePoint 2013 deployments. In this module, you will review key aspects of
the apps for SharePoint development platform, including capabilities, packaging and infrastructure, client-
side programming for SharePoint, and app security. You will also learn how to optimize the performance
of your apps.
Objectives
After completing this module, you will be able to:
 Describe the apps for SharePoint development platform.
 Use the client-side object models and the REST API to communicate with SharePoint.
 Configure security for apps for SharePoint.
 Optimize the performance of apps for SharePoint.

1-2 Creating Robust and Efficient Apps for SharePoint
Lesson 1
Apps for SharePoint
One of the key reasons for creating apps for SharePoint is that they enable you to provide custom
functionality to the widest possible range of SharePoint deployments. Apps for SharePoint are compatible
with both SharePoint Online and on-premises deployments of SharePoint 2013. Apps are also largely self-
contained and are unlikely to have unintended interactions with other SharePoint customizations, which
makes them attractive to both administrators and business users.
If you plan to distribute apps for SharePoint, you need a solid understanding of the platform that
underpins your custom functionality. In this lesson, you will review the hosting models, the packaging
process, and the infrastructure behind apps for SharePoint.
Lesson Objectives
After completing this lesson, you will be able to:
 Describe key aspects of the apps for SharePoint development platform.
 Explain the contents and structure of an app package.
 Describe how apps are distributed and managed.

 Explain the concepts behind installation scopes and app domains.
 Describe the key infrastructure requirements for apps for SharePoint.
Discussion: Why Create Apps?

To get the module started, the instructor will lead a
brief discussion around the following questions:
 What are apps for SharePoint?
 Why create an app?
Fundamentals of Apps for

SharePoint
Apps for SharePoint is essentially a framework for
integrating content from web applications into
SharePoint web pages. These web applications can
take almost any form and can run code in a variety
of ways, depending on where the app is hosted.
There are three hosting models for apps for
SharePoint:
 SharePoint-hosted apps. In a SharePoint-hosted

app, the web pages and any other resources
required by the app are deployed to a
SharePoint site. A SharePoint-hosted app
cannot execute any code on the SharePoint
Developing Microsoft SharePoint Server 2013 Advanced Solutions 1-3
server—instead, SharePoint-hosted apps must rely on running JavaScript code on the client browser
to drive any custom functionality.
 Auto-hosted apps. In an auto-hosted app, the remote web app runs on Windows Azure™. Auto-
hosted apps automatically provision and install any server-side components on Windows Azure every
time the app is installed, and each app installation has its own dedicated instance of the web
application on Azure. An auto-hosted app can also deploy declarative components to SharePoint, in
the same way as a SharePoint-hosted app. Such apps are referred to as hybrid apps.
 Provider-hosted apps. In a provider-hosted app, the web application associated with the app runs on
a remote server, which is either hosted by or at least sourced by the organization that provides the
app. As a result, provider-hosted apps can use any platform as the basis for the web application.
However, the app provider must manage how client data is isolated and managed on the server-side
web application. A provider-hosted app can also deploy declarative components to SharePoint, in the
same way as a SharePoint-hosted app.
To summarize, although users access apps through a SharePoint web page, the app logic actually runs
anywhere except on the SharePoint server.
Additional Reading: For more information on hosting models, see Choose patterns for
developing and hosting your app for SharePoint at
http://go.microsoft.com/fwlink/?LinkId=320734
App Webs and Host Webs

When you install a SharePoint-hosted app, SharePoint provisions a dedicated site (SPWeb) for the app.
The entire contents of the app, including the web pages and any other resources, are stored on this site,
which is known as the app web. By encapsulating all the app components within a SharePoint site,
SharePoint ensures that the app can be removed cleanly if the site owner uninstalls it. Auto-hosted and
provider-hosted apps can also provision an app web, but this only happens if the app needs to deploy
content to SharePoint. In auto-hosted and provider-hosted apps, the web application pages and any
associated functionality are hosted in the remote web, which is a web site that runs outside SharePoint.
When you install an app on a particular SharePoint site, the app web is created as a subsite of the current
site. The current site is then referred to as the host web. By default, an app has full control over all content
in the app web. However, the app must explicitly request permissions to access content in the host web or
elsewhere in the SharePoint farm.
Additional Reading: For more information on app webs and host webs, including app
prefixes and app IDs, see Host webs, app webs, and SharePoint components in SharePoint 2013 at
Launching an App
You can make app functionality available to users in three different ways:
 Through a full page app. In this case, users launch the app from the Site Contents page on the host
web or from a link elsewhere on the SharePoint site.
 Through an app part. In this case, users can add the app to a SharePoint page as a web part.
SharePoint displays content from the app in an iFrame.
 Through a custom action. In this case, users launch the app from a custom action. The custom action
is deployed on the host web, and consists of either a button on the ribbon or a menu item on the Edit
Control Block (ECB). You can use this option to display an app page in a SharePoint dialog box.
All apps implement a full-page user interface, but app parts and custom actions are optional.
The App Package

Apps for SharePoint are packaged and distributed
as .app files. The .app file consists of a package
format that complies with the Open Packaging
Conventions (OPC) standard for packaging data,
and you can explore the contents of an .app file by
appending .zip to the file extension and opening
the package as a .zip file.
App Manifest Files

Every app for SharePoint includes an app manifest
file named appmanifest.xml. The app manifest file
defines all the information that SharePoint requires
in order to publish and render the app to end users.
For example, the app manifest file defines:
 The start page URL for the app. This is the page that SharePoint will display when a user launches the
app. This could be a page hosted on the app web (in the case of SharePoint-hosted apps) or on a
remote server (in the case of auto-hosted or provider-hosted apps).
 The properties of the app. These properties include the title, the version number, and supported
locales.
 The permissions required by the app. The app manifest must explicitly define the level of access it
requires to any SharePoint content or services beyond the app web.
 A list of prerequisites. The app manifest must identify any SharePoint services and features that it
requires in order to operate.
 An app principal identifier. If the app is auto-hosted or provider-hosted, the app manifest must
include an identifier that enables SharePoint to authenticate and authorize the app principal.
App Package Contents

The app package always contains an app manifest file. In some cases, for auto-hosted and provider-
hosted apps, the app package may contain only an app manifest file. However, the app package may also
contain:
 Any pages and resources that must be deployed to the app web.
 Any declarative SharePoint components, typically packaged as web-scoped Features or SharePoint

solution packages (.wsp files), that must be deployed to the app web.
 Any web-scoped features that must be deployed to the host web to provision custom actions or app
parts.
 In auto-hosted SharePoint apps, Web Deploy packages and Data Tier Application Packages
(DACPACs) for deployment to Windows Azure.
Essentially, the app package contains only those components of the complete solution that SharePoint
requires. For example, if you create a provider-hosted app, the app package would contain no
components of your server-side web application.
Demonstration: Exploring an App Package

The instructor will now demonstrate how pages and declarative site assets are assembled into an app
package by Visual Studio®.
Demonstration Steps
1. Demonstrate the contents of the SiteSuggestionsApp project to the students. Point out the
following features:
 Site Columns
 Content Types
 Lists
2. Show the students the contents of the app manifest file. Highlight the Start page setting.
3. Start the app in debugging mode and then log on with the following credentials:
 User name: CONTOSO\Administrator
 Password: Pa$$w0rd
4. Create a new suggestion and like your new suggestion.
5. Close Internet Explorer®.
6. Publish the Site Suggestions App.
7. In File Explorer, rename the SiteSuggestionsApp.app file SiteSuggestionsApp.app.zip.
8. Extract the contents of the SiteSuggestionsApp.app.zip file.
9. Point out that, among other things, the app package contains an app manifest file (AppManifest.xml)
and a SharePoint solution package (SiteSuggestionsApp.wsp).
10. Use Notepad to show the contents of the AppManifest.xml file.
11. In File Explorer, rename the SiteSuggestionsApp.wsp file to SiteSuggestionsApp.wsp.cab.

12. Explore the SiteSuggestionsApp.wsp.cab file. Point out that the solution package contains all the
resources that are deployed to the app web, including pages, JavaScript files, CSS files, a Feature.xml
file, and feature manifests for each of the declarative components (site columns, content types, and
list instances).
13. Close all open windows.

Distributing Apps for SharePoint

To make an app available to SharePoint users, you
must publish it to one of two locations: an App
Catalog site collection within a specific SharePoint
deployment, or the publicly accessible Office Store
website.
App Catalogs
An App Catalog is a specialized SharePoint 2013
site collection. By default, an App Catalog contains
two document libraries: one for apps for
SharePoint, and one for apps for Office. In an on-
premises installation of SharePoint 2013, you can
create one App Catalog for each web application in
your deployment. In Office 365, each tenancy includes a single App Catalog. You publish an app to the
App Catalog by uploading the app package to the relevant document library. Users of sites within the
same web application (SharePoint 2013 on-premises) or the same tenancy (Office 365) can browse the
App Catalog and install apps, providing the user has been granted sufficient permissions.
The Office Store

The Office Store website provides a publicly accessible storefront for apps for SharePoint and apps for
Office. The Office Store collects payments from users who subscribe to your apps and provides a
framework for creating and verifying licenses. To publish an app to the Office Store, you must create a
dashboard seller account. When you submit an app to the Office Store, it goes through an approval
process prior to publication. Anyone with access to the Internet can browse the apps on the Office Store.
SharePoint users with sufficient permissions can purchase and install apps directly. Users who do not have
permission to purchase and install apps directly can create an app request in their local App Catalog. The
tenancy administrator can then choose whether to accept the request and install the app. You can find
the Office Store at the following location:
The Office Store: http://go.microsoft.com/fwlink/?LinkID=307097
Installation Scopes and App Domains

The apps for SharePoint platform is designed to
ensure that individual installations of apps are
properly isolated and encapsulated, both from each
other and from the SharePoint host environment.
This isolation can be viewed as three principles:
 Isolation of the app web. App developers must

not be able to use cross-site scripting
techniques to circumvent any restrictions on
how the app is permitted to interact with the
host web.
 Isolation of customer data. In hosted

environments, an installation of an app by one
customer must not expose data to an installation of the same app by another customer.
 Uniquely identifiable app installations. Because multiple installations of the same app may coexist in
one SharePoint deployment, SharePoint must be able to identify which specific app installation
submitted any given request.
Apps for SharePoint achieve this isolation by associating a unique security identifier and a unique DNS
domain with each individual app installation.
Installation Scopes
The apps for SharePoint framework relies on the concept of tenancy. In hosted environments, such as
Office 365, multiple customers, or tenants, share the same physical platform and the same collection of
services. The tenancy provides a logical isolation between the sites and data that belong to different
customers, to ensure that sensitive data belonging to one customer is not shared inadvertently with
another customer. In Office 365, the tenancy is the scope of your subscription—it encompasses all of your
site collections. If you deploy SharePoint 2013 on premises for the exclusive use of your own organization,
SharePoint creates a single tenancy that encompasses the entire farm.
When an administrator installs an app for SharePoint, he or she can install the app at the following scopes:
 Site scope. When you install an app into a site, there is a single host web. The app web is created as a
sub-site of the host web. The app is available only from within that host web. If you want to use the
app in another host web, you must install it a second time. Each installation of the app has a unique
security identity and is granted separate access permissions.
 Tenancy scope. When you install an app at the tenancy scope, the app web is created within the App
Catalog site collection. The app installation can be accessed from any site in the tenancy. The app has
the same security identity and access permissions, regardless of from which site the app is launched.
App Domains
SharePoint creates a unique DNS domain for each installation of an app. This DNS domain takes the
following form:
http://<app prefix>-<unique ID>.<app web hosting domain>
For example:
http://contosotenant-aa46c3ffd61233.contosoapps.com
This app URL consists of three distinct components:
 The app prefix. This is configured at the tenancy scope, either through PowerShell or through the
Central Administration website.
 The unique app ID. SharePoint generates a unique ID for each installation of an app.
 The app web hosting domain. This is a global, top-level domain for all your app installations.
To support isolation and prevent cross-site scripting, Microsoft recommends that you create a unique top-
level domain for your apps. For example, if your top-level domain for SharePoint is contoso.com, you
might create a top-level domain for your SharePoint apps of contosoapps.com.
Infrastructure for Apps

SharePoint 2013 relies on two service applications
to manage apps for SharePoint:
 App Management Service. This service

application tracks and manages installed apps.
The App Management Service uses a database
to store configuration data for each installed
app, including the app domain, app principal,
app identifier, and license details.
 Subscription Settings Service. This service

application tracks and manages the tenancies
on a SharePoint server farm. Because apps for
SharePoint run within the scope of a tenancy,
this service application must be configured before you can use apps for SharePoint.
In an Office 365 subscription, these service applications are provisioned and available by default. In an on-
premises installation, an administrator must set up these service applications as part of the farm
configuration process.
Lesson 2
Communicating with SharePoint from an App
When you develop apps for SharePoint, you can use three main approaches to communicate with the
SharePoint server. These approaches are the JavaScript object model, the managed client object model,
and the REST API. All of these approaches rely on a web service, client.svc, which SharePoint exposes on
every site. When you use the REST API, you communicate with the client.svc service directly. By contrast,
the JavaScript object model and the managed client object model work by providing client-side proxies
for the client.svc service.
In this lesson, you will review the core programming techniques that you can use with the JavaScript
object model, the managed client object model, and the REST API. You will also review where you can use
each approach, and consider the advantages and disadvantages of these programming models in various
scenarios.
Lesson Objectives
 Describe the core concepts behind the SharePoint 2013 REST API.
 Perform create, retrieve, update, delete, and query (CRUDQ) operations with the REST API.
 Describe the core concepts behind the JavaScript object model.
 Use encapsulation patterns to write robust JavaScript code.

 Handle errors with the JavaScript object model.
 Use the managed client object model to perform basic operations.
Using the SharePoint 2013 REST API

Representational State Transfer (REST) is a design
pattern for web services that provide access to data
sources. The Open Data Protocol (OData) is a
protocol that builds on REST to provide a
standardized way of interacting with a data source
through a web service. In SharePoint 2013, the REST
API is provided by an OData-compliant, REST-based
web service, client.svc, that you can use to perform
a wide range of tasks from client-side or remote
server code.
Key Concepts
The SharePoint 2013 REST API has various
characteristics that are common to all REST/OData web services:
 Data entities are represented by URIs. You identify the object or collection you want to work with by
constructing a URI within the web service URL. For example, to select a list called Discussion you could
use the URI /_api/web/lists/getbytitle('Discussion').
 Data operations are mapped to HTTP verbs. You specify the data operation you want to perform (such
as create, retrieve, update, or delete) by using the corresponding HTTP verb (POST, GET, PUT, and
DELETE).
 Data is exchanged in an OData-compliant format. You can use OData query operators such as $select,
$order, and $filter within your request URLs. The service returns data in either Atom Publishing
Protocol (AtomPub) or JavaScript Object Notation (JSON) format.
Constructing REST API URLs

The client.svc web service is exposed at the site-relative URL _vti_bin/client.svc. To simplify the
construction of RESTful URLs, SharePoint provides a shortcut that enables you to access the web service at
the site-relative URL _api. For example, if you are working with a SharePoint site at
http://intranet.contoso.com, you can access the REST API at http://intranet.contoso.com/_api.
You can build on this root service URL to identify specific SharePoint objects and collections. The
following table shows examples of common REST URLs:
URL Description
http://intranet.contoso.com/_api/site Returns the site collection

object and its properties.
http://intranet.contoso.com/_api/site/owner Returns the SPUser object for

the user who created the site
collection.
http://intranet.contoso.com/_api/web Returns the site (SPWeb)

object and its properties.
http://intranet.contoso.com/_api/web/currentuser Returns the SPUser object for

the current user.
http://intranet.contoso.com/_api/web/lists Returns a collection of all the

lists and libraries to which the
current user has at least read
access in the current
SharePoint site.
http://intranet.contoso.com/_api/web/lists/getbytitle("Invoices") Returns the list with the title

Invoices.
http://intranet.contoso.com/_api/web/lists/getbytitle("Invoices")/items Returns all items in the list

with the title Invoices.
Using OData Query Operators

You can filter or limit the number of items returned by these URLs by including OData query operators as
query strings in your URLs. For example, the following URL returns all items in the Invoices list, but only
populates the Title and Amount fields for each item:
/_api/web/lists/getbytitle("Invoices")/items?$select=Title,Amount
The following URL skips the first 10 items in the Invoices list and returns the next 10 (for example to
implement paged results):
/_api/web/lists/getbytitle("Invoices")/items?$skip=10&$top=10
Performing CRUD Operations with REST

The HTTP request you submit to a RESTful web
service is platform agnostic—that is, the format of
the request is the same regardless of the platform
from which it is submitted. However, the techniques
you use to build the request and handle the
response will vary from platform to platform. In this
topic, we will look at performing REST API
operations from JavaScript by using jQuery.
Note: When you need to build a URL for a

REST API request from within a SharePoint page,
you can use the
_spPageContextInfo.webServerRelativeUrl property to retrieve the server-relative root URL of
the current SharePoint site.
Reading Data
To use the REST API to retrieve data, you submit an HTTP GET request. There are two jQuery functions
that are useful when you want to retrieve data from the REST API in JavaScript code:
 The $.getJSON() function. This provides a simple and easy-to-use way of requesting and receiving
JSON data.
 The $.ajax() function. This provides a more sophisticated way of constructing REST URLs and
submitting requests, for when you need more control over how the request is created.
The following code example shows how to create REST requests and handle the responses by using
JavaScript and jQuery. The first request uses the getJSON() function to retrieve details of the current
website. The second request uses the ajax() function to retrieve details of the current user.
Reading Data from the REST API

$.(document).ready( function() {
//Formulate the URL to get the current web site
var websiteRequestURL = _spPageContextInfo.webServerRelativeUrl + "/_api/web"
///Formulate the URL to get the current user
var userRequestURL = _spPageContextInfo.webServerRelativeUrl + "/_api/web/currentuser"
//Use getJSON() to find out about the current web site
$.getJSON(websiteRequestURL, function (data) {
alert("The current web site has the title " + data.d.Title);
});
//Use ajax() to find out about the current user
$.ajax({
url: userRequestURL,
type: "GET",
headers: {
"accept": "application/json;odata=verbose"
},
success: function (data) {
alert("The current user has the name " + data.d.Title);
},
error: function (err) {
alert("There was an error obtaining the user name");
}
});
});
Creating, Updating, and Deleting Data

When you want to use the REST API to create, update, or delete data on SharePoint, you construct the
URL in exactly the same way as you would to retrieve data. You specify the action you want to perform by
including an appropriate HTTP verb with your request. You can use the following HTTP verbs:
 POST. Use the POST verb when you want to create a new item.
 PUT. Use the PUT verb when you want to overwrite an existing item. If you use the PUT verb, you
must specify all the properties of the item—both the properties that have changed and the properties
that remain the same.
 PATCH. Use the PATCH verb when you want to modify an existing item. If you use the PATCH verb,
you need only specify the properties that you want to change.
 MERGE. The MERGE verb performs a similar role to the PATCH verb, but PATCH is used more
frequently by convention.
 DELETE. Use the DELETE verb when you want to delete an existing item.
If you want to use anything other than a GET verb, you must use the $.ajax() function to construct your
request.
To perform a create, update, or delete operation, you must include a form digest with your request. The
form digest is a hash of the page content, and is used to prove that the request comes from the original
page as sent from the SharePoint server. To include the form digest with your request, you must:
1. Retrieve the contents of the page element with ID __REQUESTDIGEST.
2. Add the contents of the digest to the X-RequestDigest header in your request.
The following code example shows how to create, update, and delete list items from a Suggestions list on
the SharePoint site:
Creating, Updating, and Deleting Data with the REST API

"use strict";
var Contoso = window.Contoso || {};
Contoso.SuggestionsList = function () {
create = function (subject, feedback) {
//To create an item, formulate a URL to the parent list
var listUrl = _spPageContextInfo.webServerRelativeUrl +
"/_api/web/lists/getByTitle('Suggestions')/items";
//Store the form digest
var formDigest = $('#__REQUESTDIGEST').val();
$.ajax({
url: listUrl,
type: "POST",
data: JSON.stringify({
'__metadata': { 'type': 'SP.Data.SuggestionsListItem' },
'Subject': subject,
'Feedback': feedback
}),
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": formDigest
},
success: function () {
alert("Successfully created the suggestion");
},
alert("Could not create the suggestion");
}
});
},
update = function (id, subject, feedback) {
//To update an item, formulate a URL to the item itself

"/_api/web/lists/getByTitle('Suggestions')/getItemByStringId('" + id + "')";
$.ajax({
url: listUrl,
type: "POST",
'__metadata': { 'type': 'SP.Data.SuggestionsListItem' },
'Subject': subject,
'Feedback': feedback
}),
headers: {
"X-RequestDigest": formDigest,
"IF-MATCH": "*",
"X-Http-Method": "PATCH"
},
alert("Successfully updated the suggestion");
},
alert("Could not update the suggestion");
}
},
delete = function (id) {
//To delete an item, formulate a URL to the item itself
"/_api/web/lists/getByTitle('Suggestions')/getItemByStringId('" + id + "')";
$.ajax({
url: listUrl,
type: "DELETE",
headers: {
"X-RequestDigest": formDigest,
"IF-MATCH": "*"
},
alert("Successfully updated the suggestion");
},
alert("Could not update the suggestion");
}
}
return {
createSuggestion: create,
updateSuggestion: update,
deleteSugestion: delete
}
} ();
Using the JavaScript Object Model

In SharePoint 2013, the JavaScript object model
provides a way of interacting with a SharePoint
deployment from JavaScript code running in a web
page. The JavaScript object model is typically used
in pages that are served from the app web for an
app for SharePoint. However, you can also use the
JavaScript object model in remote web pages with
the help of the cross-domain library, which is
described in the next lesson.
The JavaScript object model consists of several

JavaScript library files, such as sp.js and
sp.runtime.js, which you can find in the LAYOUTS
folder in the SharePoint server file system. The object model essentially provides a proxy for the client.svc
web service, which SharePoint exposes on every site. Any operations that you perform in the JavaScript
object model are batched and sent to the client.svc service as XML when you execute your query or
operation.
Whenever you use the JavaScript object model, your first task is to create a client context object. The client
context object—SP.ClientContext in the JavaScript object model—represents the current location of the
user within SharePoint, and is conceptually similar to the server-side SPContext object. You can
instantiate a client context object by calling the SP.ClientContext.get_current method:
var context = new.SP.ClientContext.get_current();
The client context object provides the entry point for all JavaScript object model operations. For example:
 You use the context.load method to specify objects that you want to retrieve from the server.
 You use the context.loadQuery method to specify a LINQ to objects query that you want to execute
on the server.
 You use the context.executeQueryAsync method to send the operations you have performed to the
server.
Like most JavaScript functions, the functions in the JavaScript object model use an asynchronous
programming model. None of your operations are sent to the server until you call the
executeQueryAsync method. When you call the executeQueryAsync method, you specify callback
functions to handle the response from the server.
The following code example shows how to load an object into the client context, execute the operation
asynchronously, and then display the results:
Loading an Object Asynchronously

"use strict";
var Contoso = window.Contoso || {}
Contoso.SiteCollection = function () {
var siteCollection,
context,
getSiteCollection = function () {
context = new SP.ClientContext.get_current();
siteCollection = context.get_site();
context.load(siteCollection, "Title", "ServerRelativeUrl");
context.executeQueryAsync(onSuccess, onFailure);
},
onSuccess = function () {
alert("Site Collection URL: " + siteCollection.get_url());
},
onFailure = function(sender, args) {
alert("Could not obtain the site collection URL");
}
return {
execute: getSiteCollection
}
}();
$(document).ready(function () {
Contoso.SiteCollection.execute();
});
In this example, notice that:
 You retrieve a reference to the current site collection from the client context object.
 You use the context.load method to specify that you want to retrieve the Title and
ServerRelativeUrl properties of the site collection object from the server.
 You use the executeQueryAsync method to send the query to the server.
 You use the onSuccess and onFailure callback functions to handle the response from the server.
 You use the $(document).ready function to run your code when the page has finished loading.
Note: The code example in this topic uses the module pattern for encapsulating JavaScript
code. The module pattern is described in the next topic.
Developing Robust JavaScript Code

JavaScript is far less rigorous than managed code
languages such as C# when it comes enforcing rules
on types, variable names, and scopes. When you
use JavaScript code in SharePoint pages, such as
within an app for SharePoint, you should take extra
care to ensure that your code is manageable,
robust, and easy to troubleshoot. In particular, you
should:
 Use strict JavaScript.
 Use a programming pattern that encapsulates

your code.
Strict JavaScript
Strict JavaScript was introduced in version 5 of the ECMAScript language specification. Essentially, strict
JavaScript is a more robust variant of JavaScript that prevents a wide range of common programming
errors. It achieves this by enforcing more rigorous programming rules and by throwing errors where code
would otherwise fail silently.
You can invoke strict mode at two scopes:
 Script scope. To apply strict mode to an entire JavaScript file, add the statement 'use strict'; as the
first line of the script.
 Function scope. To apply strict mode to an individual function, add the statement 'use strict'; in the
body of the function before any other statements.
Note: Although invoking strict mode at the script scope is less time-consuming, it can
cause unexpected behaviors if you concatenate strict mode scripts and non-strict mode scripts.
Strict mode changes the syntax and execution of JavaScript in a variety of ways. For example, strict mode
will:
 Prevent you from using a variable without first declaring it.
 Prevent you from writing to a read-only property.
 Prevent you from duplicating property and parameter names.
 Prevent you from adding properties to non-extensible objects.
 Prevent the value of the this keyword from defaulting to the global window object.
 Prevent you from using reserved keywords as names for functions or variables.
Additional Reading: For more information on strict mode, see Strict Mode (JavaScript) at
http://go.microsoft.com/fwlink/?linkId=320736
Encapsulating Code
By default, JavaScript functions and variables are added to the global namespace. The global namespace is
a container for all the JavaScript associated with a web page, and is represented by the window object.
When you write JavaScript code, you should avoid adding functions or variables to the global namespace.
This can lead to naming conflicts when pages are rendered and can make code difficult to debug. Instead,
you should create a custom namespace within the global namespace, and add your functions and
variables to the custom namespace. The following code shows how to create a custom namespace:
Within your custom namespace, there are various patterns you can use to encapsulate your code. In
object-oriented programming, encapsulation refers to the concept of creating a container or object that
represents both a data entity and the methods or functions that operate on the data entity. Encapsulation
is especially important for JavaScript developers. A web page will often load multiple scripts, in many
cases created by different people or different organizations, and encapsulation helps to reduce
unexpected interactions or conflicts.
One of the most popular encapsulation patterns for JavaScript is the module pattern. When you use the
module pattern, you use a function to encapsulate an entity and any logic associated with the entity. You
can use the module pattern to associate both private and public members with your entity, and to create
multiple instances of the same entity. This makes the programming experience familiar to users of object-
oriented programming languages such as Visual C#.
The following code example shows how to use the module pattern to encapsulate operations on a
Suggestions list on a SharePoint site:
Using the Module Pattern

"use strict";
var Contoso = window.Contoso || {}
Contoso.SuggestionsList = function () {
createSuggestion = function (subject, feedback) {
//Get the client context and suggestions list
var context = new SP.ClientContext.get_current();
var list = context.get_web().get_lists().getByTitle("Suggestions");
context.load(list);
//Create the new item and set fields.
var listItemCreationInfo = new SP.ListItemCreationInformation();
var newItem = list.addItem(listItemCreationInfo);
newItem.set_item("Subject", subject);
newItem.set_item("Feedback", feedback);
//Remember to call update before executing the query
newItem.update();
context.executeQueryAsync(onSuccess, onError);
},
updateSuggestion = function (id, subject, feedback) {
context.load(list);
var itemToUpdate = list.getItemById(id);
itemToUpdate.set_item("Subject", subject);
itemToUpdate.set_item("Feedback", feedback);
//Remember to call update before executing the query
newItem.update();
},
removeItem = function (id) {
context.load(list);
//Get the item from its ID
var itemToDelete = list.getItemById(id);
//delete it before executing the query
itemToDelete.deleteObject();
},
onSuccess = function () {
alert("The operation completed successfully);
},
onError = function (sender, args) {
alert("The operation caused an unexpected error);
};
return {
Create: createSuggestion,
Update: updateSuggestion,
Delete: removeSuggestion
};
} ();
In the previous example, all the logic is encapsulated in a function named SuggestionsList within the
Contoso namespace. The return values of the function map public members to internal members. For
example, to add a new suggestion to the list, you could use the following code:
Contoso.SuggestionsList.Create("Your Subject", "Your feedback text.");
Discussion: REST API Versus JavaScript Object Model

The instructor will now lead a brief discussion
around the following question.
If you write JavaScript code for an app, you can use

either the REST API or the JavaScript object model
to communicate with SharePoint. In what
circumstances would you use each approach?
Resolving Errors with the JavaScript

Object Model
The asynchronous nature of the JavaScript object
model provides built-in support for client-side error
handling. As you have seen already, when you send
a query to the server by calling the
executeQueryAsync method, you specify the
names of two functions as arguments. The first
function is called if the operation is successful, and
the second function is called if the operation fails.
You can use the failure callback function to retry
the operation or alert the user to the problem.
The downside of this approach is that these callback

functions are not invoked until the server responds
to the client. A single call to the client.svc service may contain many batched operations. If one of these
operations causes an error on the server, the entire batch is treated as a failed query and you have no way
of ensuring that subsequent operations are completed.
For a more sophisticated approach to error handling, the JavaScript object model provides a mechanism
that you can use to send error handling instructions to the server. This mechanism is provided by the
ExceptionHandlingScope object. The ExceptionHandlingScope object enables you to present your
query logic as a try-catch-finally block. When your query is submitted to the server:
1. The server will first try to execute the instructions in the try block.
2. If an exception occurs, the server will execute the instructions in the catch block.
3. Regardless of whether or not an exception occurred, the server will execute the instructions in the
finally block.
The following code example shows how to structure a query by using the ExceptionHandlingScope
object:
Using an Exception Handling Scope

// Create a new exception handling scope.

var scopeObject = new SP.ExceptionHandlingScope(context);
// Start the scope.

var scopeBlock = scopeObject.startScope();
// Define the try block.

var tryBlock = scopeObject.startTry();
//Place code that may generate exceptions here
tryBlock.dispose(); //This call to dispose marks the end of the try block
// Define the catch block.

var catchBlock = scopeObject.startCatch();
//Place code that handles exceptions here
catchBlock.dispose(); //This call to dispose marks the end of the catch block
// Define the finally block.

var finallyBlock = scopeObject.startFinally();
//Place code that should execute regardless of errors here
finallyBlock.dispose(); //This call to dispose marks the end of the finally block
// End the scope.

scopeBlock.dispose();
// Execute the query

context.executeQueryAsync(onSuccess, onFailure);
Using the Managed Client Object Model

In SharePoint 2013, you can use the managed client
object model to interact with SharePoint from code
running in a remote .NET application, such as in an
ASP.NET MVC web application or a mobile app. Like
the JavaScript object model, the managed client
object model provides a client-side proxy for the
client.svc service. The managed client object model
provides a very similar set of functionality to the
JavaScript object model, and many of the class or
function names and approaches to tasks are the
same. The main difference is that the managed
client object model reflects the object-oriented
nature of .NET programming languages such as C#. The managed client object model also enables you to
execute queries synchronously as well as asynchronously.
Like the JavaScript object model, the first task whenever you use the managed client object model is to
retrieve a client context object. The following code example shows how to create and use a client context
object by using the managed client object model in C#:
Using the Client Context Object

public string getSiteCollectionUrl () {
string appWebUrl = Page.Request["SPAppWebUrl"];
using (ClientContext context = new ClientContext(appWebUrl));
{
Site siteCollection = context.Site;
context.Load(siteCollection, s=>s.Title, s=>s.ServerRelativeUrl);
context.ExecuteQuery();
return siteCollection.Url;
}
}
In this example, notice that:
 You use the appWebUrl token to instantiate the client context object. For remote-hosted apps,
SharePoint provides the value of the appWebUrl token in the SPAppWebUrl page request
parameter.
 You retrieve a reference to the current site collection from the client context object.
 You use the context.load method to specify that you want to retrieve the Title and
ServerRelativeUrl properties of the site collection object from the server, by providing a lambda
expression.
 You use the ExecuteQuery method to send the query synchronously to the server.
 You can access resources in the app web from .NET managed client object model in the remote web
without using tokens and without permission requests to resources in the host web.
Like the JavaScript object model, the managed client object model enables you to use exception-handling
scope objects to send error-handling instructions to the server with your queries.
Lesson 3
Authenticating and Authorizing Apps for SharePoint
As your apps for SharePoint become more sophisticated, the authentication and authorization
requirements of your apps are likely to become more demanding. If your app needs access to SharePoint
data beyond the app web, you will need to configure permission requests in the app manifest file. If you
create an auto-hosted or provider-hosted app, you will need to register an app principal and configure a
trust relationship with the SharePoint server farm. You will also need to work with tokens and token
helper classes when you communicate with SharePoint. Finally, if you want to access data across domain
boundaries from code running in a browser window, you will need to understand how SharePoint can
help you to circumvent browser restrictions designed to prevent cross-site scripting (XSS) attacks.
Lesson Objectives
 Describe the security model for apps for SharePoint.
 Explain how apps are authenticated and authorized.
 Describe how to register an app principal for auto-hosted and provider-hosted apps.
 Configure an app manifest file to request SharePoint permissions.
 Use token helper classes to work with security tokens.
 Use the cross-domain library and the web proxy to communicate across domain boundaries.
The App Security Model

In SharePoint 2013, an app for SharePoint is a
security principal. In computing terminology, a
security principal is an entity that can be
authenticated by a system. For example, user
accounts and computer accounts are both
examples of security principals.
Because an app is a security principal, you can grant

permissions to apps in addition to granting
permissions to users. When an app attempts to
access resources on a SharePoint server on behalf of
a user, SharePoint must be able to authenticate
both the app and the user.
App Principals and App Identifiers

An app principal is the component of an app for SharePoint that represents the app as a security principal.
Just as users have user accounts, apps have app principals. App principals include the following
information:
 Client ID. This is a globally unique identifier (GUID) that uniquely identifies the app. The client ID is
often referred to as the app ID.
 Title. This is a human-readable name for the app.
 Client secret. If the app is remote-hosted, the app principal will contain an encryption key for
encrypting security tokens.
 Remote host domain. If the app is remote-hosted, the app principal will contain the DNS domain of
the remote host.
 Redirect URL. This is an optional setting that enables remote-hosted apps to request permissions
during operations.
When you install a SharePoint app, the app principal is registered with the SharePoint tenancy. This
creates an app identifier, which is a unique string that includes the app client ID and the tenancy ID. When
SharePoint assigns a permission to your app, it stores the permission with the app identifier. This means
that each app permission in SharePoint is specific to one installation of one app.
In a SharePoint hosted app or an auto-hosted app, SharePoint automatically creates an app principal and
an app identifier every time a user installs your app. Although you must understand app principals for
these types of apps, you do not need to create them yourself.
App Permissions
When you install an app, the app automatically has full control permissions on the app web. However, the
app does not have any permissions on the host web. If you are creating an app that requires access to
content or services on SharePoint, you must add permission requests to the app manifest file. When a user
installs the app, SharePoint will prompt them to grant the requested permissions to the app. This is an all
or nothing choice: The user must either grant all the requested permissions, or abort the installation.
A user can only grant permissions to an app if they have the requested permissions themselves. For
example, if a user has read-only access to a list, he or she cannot grant an app write access to the list.
App Authentication
Typically, when SharePoint receives a request, it
must first authenticate the user. It uses an
authentication provider (such as Active Directory
Domain Services) to verify the credentials of the
user, and it issues a security assertion markup
language (SAML) token to the user. The client
browser or application submits the SAML token
with subsequent requests as proof of the user's
identity.
This situation becomes more complicated when

apps are involved. Because apps for SharePoint are
security principals in their own right, if a request
originates from an app, SharePoint must authenticate the app as well as the user. SharePoint must
perform app authentication only when one of the following conditions are met:
 The request targets a service endpoint within an app domain. This indicates that the request originates
from an app, as cross-site scripting restrictions will prevent service calls from outside the app domain.
 The request includes an app-specific type of security token—an access token—instead of a SAML token.
This indicates that the request originates from a remote-hosted app.
SharePoint uses three different authentication techniques for apps for SharePoint. The three types of app
authentication are:
 Internal app authentication.
 External app authentication by using OAuth.
 External app authentication by using server-to-server (S2S) trust relationships.

Note: App authentication is only required for calls to the client.svc service—in other words,
calls that originate from the client-side object model (CSOM) or the REST API. Regular user
authentication is used in the case of standard HTTP requests.
Internal App Authentication

In internal app authentication, SharePoint authenticates the app principal in a similar way to how it
authenticates a user. This approach uses the authentication mechanism associated with the SharePoint
web application. Internal app authentication is used when SharePoint has already authenticated the user
associated with the service call. In this case, the call includes the SAML token that SharePoint issued to the
user. SharePoint-hosted apps always use internal app authentication. This is because the service call will
always originate from a SharePoint-hosted app web and will always target an endpoint in the same
domain, and therefore there will always be a SAML token for the user associated with the request.
SharePoint knows it must use internal app authentication when:
 The service call targets a service endpoint within an app web domain, and
 The service call includes a SAML token for an authenticated user.
In this case, SharePoint can establish the identity of the app internally. The identity of the app is added to
the call context, along with the identity of the user, where it can be used for authorization.
External App Authentication with OAuth

In many cases, SharePoint cannot use internal app authentication to authenticate calls from remote-
hosted apps. If the call originates from a remote server, rather than the client browser, then the call will
not include a SAML token for the authenticated user.
In these scenarios, you must configure the app to use external authentication. When an app is configured
to use external authentication, an external system must verify the identity of the user and the app. This
external system generates a context token that is sent to SharePoint with the service call. The context
token states both the identity of the user and the identity of the app (or less commonly, just the identity
of the app).
External authentication relies on a trust relationship between the SharePoint server and the external
system that issues context tokens. One approach to providing this trust relationship is to use Windows
Azure Access Control Service (ACS), which is an OAuth provider. In this case, you must register your app
security principal with ACS so that your app can request access tokens. ACS issues an access token that
contains both the app ID and the user ID, and the app sends this token to SharePoint with the service call.
External authentication with OAuth is typically used for auto-hosted apps. In this case, the trust
relationship between Office 365 and ACS is configured automatically, which makes this approach simple
and effective.
External App Authentication with S2S

The other approach to external app authentication is to use S2S authentication. This is typically used in
provider-hosted apps, where configuring a trust relationship with ACS is less straightforward.
In external authentication with S2S, an administrator configures a server-to-server trust relationship

between the SharePoint server and the server that hosts the remote web application. The trust
relationship is based on X.509 certificates. When the app makes a service call to SharePoint, it creates an
access token and signs it using the private key. The SharePoint server uses the public key to verify that the
token originated from the trusted remote server.
Registering an App Principal

When you install an app, you must register the app
principal with SharePoint. In SharePoint-hosted and
auto-hosted apps, the app principal is registered
automatically. In these cases, you just need to
understand how the app is configured and how the
process works at a high level. For provider-hosted
apps, you must manually register the app principal.
SharePoint-Hosted Apps
When you create a SharePoint-hosted app, the app
will be preconfigured to use internal authentication.
You do not have to change this configuration.
However, you should understand how the
configuration is represented in the app manifest file.
The following code example shows how SharePoint-hosted apps are configured to use internal
authentication in the app manifest file:
Configuring a SharePoint-Hosted App to Use Internal Authentication

<AppPrincipal>
<Internal />
</AppPrincipal>
Auto-Hosted Apps
When you create an auto-hosted app for SharePoint, the app principal is created and registered with
SharePoint automatically. The app tells SharePoint to create and register an app principal automatically by
including an AutoDeployedWebApplication element in the app manifest file.
The following code example shows how auto-hosted apps are configured to create and register an app
principal automatically:
Configuring an Auto-Hosted App

<AppPrincipal>
<AutoDeployedWebApplication />
</AppPrincipal>
When you create an auto-hosted app in Visual Studio 2012, Visual Studio adds two configuration settings
to the web.config file for the remote web. These are the client ID and the client secret. The values in the
web.config file must match the corresponding values in the app principal.
The following example shows how the client ID and the client secret are configured in the remote
web.config file:
Web.config Settings for Auto-Hosted Apps

<configuration>
<appSettings>
<add key="ClientId" value="12345678-1234-1234-1234-123456789012" />
<add key="ClientSecret" value="fjewk4fcnekrgsl29fcnder7xwer21FEGcegD47D2VFf=" />
</appSettings>
</configuration>
Provider-Hosted Apps
When you create a provider-hosted app, you must register the app principal manually with the SharePoint
farm. You can do this in two ways:
 Use the AppRegNew.aspx page. This is an application page that SharePoint exposes on every site
through the LAYOUTS directory. The page prompts you for a client ID, a client secret, a title, an app
domain, and an optional redirect URL. The page can also generate a client ID and a client secret for
you, if required.
 Use Windows PowerShell. You can use the Register-SPAppPrincipal cmdlet to register your app
principal with SharePoint.
You must also have configured a S2S trust relationship between the SharePoint server and the remote app
host, as described earlier in this lesson.
When you configure the app manifest file for a provider-hosted app, you must add a
RemoteWebApplication element to the AppPrincipal element. The RemoteWebApplication element
must also include the client ID of the app principal.
The following code example shows how to configure the app principal in the app manifest file for a
provider-hosted app:
Configuring the App Principal for a Provider-Hosted App

<AppPrincipal>
<RemoteWebApplication ClientId="12345678-1234-1234-1234-123456789012" />
</AppPrincipal>
You must also add the ClientId and ClientSecret settings to the remote web.config file, in the same way
as you would for an auto-hosted app.
Requesting Permissions
Any app that creates an app web, such as a
SharePoint-hosted app, has full access to all the
resources in that app web. However, to access
resources in the host web or elsewhere on
SharePoint, the app must request the required
permissions during installation. These permissions
are explained to the user, who can choose to trust
the app and grant all the requested permissions, or
to cancel the installation.
If you are developing an app that will request

permissions beyond the app web, you must add
these permission requests to the app manifest file.
For each permission you need to request, you must add an AppPermissionRequest element to the
AppPermissionRequests element in the app manifest file. Each AppPermissionRequest element
includes:
 A Scope attribute. This specifies the object or service that the app needs to access.
 A Right attribute. This specifies the required permission level.

Permission Scopes and Rights

In the AppPermissionRequest element, the Scope attribute is specified in a URI format (although it is
not technically a URI). The value of the Right attribute is usually either Read, Write, Manage, or
FullControl, although specific service applications may use different Right attribute values. The easiest
way to understand permission scopes is to look at some examples.
You can use the following Scope values to request access to SharePoint data:
Access required Scope URI Available rights
The current tenancy http://sharepoint/content/tenant Read, Write, Manage, FullControl
The current site http://sharepoint/content/sitecoll Read, Write, Manage, FullControl

collection ection
The host web http://sharepoint/content/sitecoll Read, Write, Manage, FullControl

ection/web
The lists on the host web http://sharepoint/content/sitecoll Read, Write, Manage, FullControl
ection/web/list
You can use the following Scope values to request access to SharePoint services:
Access required Scope URI Available rights
Managed Metadata http://sharepoint/taxonomy Read, Write

Service
Search http://sharepoint/search QueryAsUserIgnoreAppPrincipal
Business Connectivity http://sharepoint/bcs/connection Read

Services
Social microfeed http://sharepoint/social/microfeed Read, Write, Manage, FullControl
Additional Reading: For a comprehensive list of Scope URI values and the corresponding
available rights, see App permissions in SharePoint 2013 at
The following code example shows how to use AppPermissionRequest elements to request permissions in
the app manifest file:
Requesting App Permissions

<AppPermissionRequests>

<AppPermissionRequest
Right="Read"
Scope="http://sharepoint/content/sitecollection/web" />

Right="Write"
Scope="http://sharepoint/content/sitecollection/web/lists" />

Right="Read"
Scope="http://sharepoint/content/tenant" />

Right="QueryAsUserIgnoreAppPrincipal"
Scope="http://sharepoint/search" />

Right="Write"
Scope="http://sharepoint/social/microfeed" />
</AppPermissionRequests>
Refining Permission Scopes

The examples in this topic show broad permission scopes: the app requests access to the entire tenancy,
or the entire site collection, or to every list on the host web. In many cases, you may want to refine these
scopes, for example to identify the specific lists to which you require access. You can do this by including
one or more Property elements within the AppPermissionRequest element.
The following code example shows how to use Property elements to refine a permission request:
Refining a Permission Request

<AppPermissionRequest Right="Read"
Scope="http://sharepoint/content/sitecollection/web/lists">
<Property Name="BaseTemplateId" Value="101" />
</AppPermissionRequest>
In this example, the permission request is constrained to only those lists with a base template ID of 101, or
in other words to document libraries, within the host web.
Discussion: Requesting Permissions

The instructor will now lead a brief discussion
around the following scenario:
You create a SharePoint-hosted app that enables

users to look up additional information about
customers in a Contacts list. Users launch your app
from the Edit Control Block (ECB) on items in the
Contacts list on the host web. The app reads data
from the list item in the Contacts list. It uses this
data to retrieve additional information about the
customer from a customer relationship
management (CRM) web service. It displays the
additional information to the user in a SharePoint
dialog box.
How would you configure permission requests for this app?

Working with Tokens

When you create a SharePoint-hosted app, you can
largely ignore the authentication process.
SharePoint issues a SAML token to the user and
authenticates your app internally. However, when
you create remote-hosted apps—both auto-hosted
apps and provider-hosted apps—you will need to
work with various types of security tokens to ensure
that your app works properly.
Token Types
SharePoint uses the following types of security
tokens when it communicates with an app:
 Context Tokens. Context Tokens are issued by Windows Azure ACS and include user identity, the
tenancy identity, and the URL of the host web. ACS first sends the context token to the SharePoint
host environment. SharePoint then passes the token to the remote web, by including the token in a
form variable named SPAppToken as part of the HTTP POST. Context tokens are issued only by
OAuth providers (in this case, Windows Azure ACS) and are not used in S2S trusts.
 Access Tokens. An access token is issued when a client is authenticated. When you submit a request
from a remote app, you must include the access token in the HTTP header to prove that your client is
authenticated. In Visual Studio 2012, the App for SharePoint project template includes a class named
TokenHelper that can help you to work with access tokens.
 Refresh Tokens. Like context tokens, refresh tokens are specific to OAuth providers. When ACS issues a
context token, the context token includes a refresh token. When an app needs to authenticate, it
submits the refresh token to ACS. ACS validates the refresh token and issues an access token. An
access token expires 12 hours after it is issued, whereas a refresh token is valid for six months. As such,
you may wish to store refresh tokens—for example, in a database associated with the remote web—
to expedite the authentication process.
The TokenHelper Class

When you create a remote-hosted app in Visual Studio 2012, the App for SharePoint project template
includes a class named TokenHelper. The TokenHelper class includes a set of utility methods that can
help you to retrieve tokens programmatically and to include tokens in HTTP headers when you make a
service call to the SharePoint server by using the client-side object model or the REST API. For example,
the TokenHelper class includes the following static methods:
 TokenHelper.GetContextTokenFromRequest. If you are using OAuth to authenticate your app, you

can use this method to obtain a context token from the Page.Request object.
 TokenHelper.GetClientContextWithContextToken. If you are using OAuth to authenticate your

app, you can use this method to obtain an access token by providing a context token. The
GetClientContextWithContextToken method returns a client context object. Whenever you execute
a query using the client context returned by this method, the access token is included by default.
 TokenHelper.GetS2SAccessTokenWithWindowsIdentity. If you are using S2S to authenticate your

app, you can use this method to get an access token by specifying a Windows identity.
The following code example shows how to retrieve a context token and then use it to create a client
context that includes an access token:
Working with OAuth Tokens

// Store the context token (OAuth only).
var contextToken = TokenHelper.GetContextTokenFromRequest(Page.Request);
// Store the host web URL, which is in the SPHostUrl request parameter.
var hostURL = Page.Request["SPHostUrl"];
// Get a client context object that includes an access token.

using (var context = TokenHelper.GetClientContextWithContextToken(hostURL, contextToken,
Request.Url.Authority))
{
// Submit a query. The client context object will include the access token when it
submits the query.
context.Load(context.Web);
context.ExecuteQuery;
}
Communicating Across Domain Boundaries

In many scenarios, you will want to develop apps
that access data and call services that reside in
different domains. However, to prevent XSS attacks,
modern browsers only permit web pages to call
services or run scripts that originate from the same
domain as the web page itself. SharePoint 2013
includes two mechanisms that you can use to
circumvent these XSS restrictions without
jeopardizing user security:
 The cross-domain library. This enables a
remotely served web page to access resources
in a SharePoint app web.
 The web proxy. This enables a web page to access resources from other domains by routing the
request through the SharePoint server.
The Cross-Domain Library

Suppose you create a provider-hosted app for SharePoint. You could use server-side code to call into the
app web without encountering any XSS restrictions. However, there are many reasons why you might
prefer to execute your logic from the client; for example to reduce server load, improve user experience,
or avoid firewall issues. In these scenarios, you can use the cross-domain library to access resources in the
app web. You can use the cross-domain library with both the JavaScript object model and the REST API.
The cross-domain library is contained in a file named SP.RequestExecutor.js, which is available from the
SharePoint LAYOUTS directory. You can add this file directly to remote web projects when you want to
use the cross-domain library. The functionality of the library is provided by the SP.RequestExecutor
object. For example, it includes a method named executeAsync that you can use to submit cross-domain
service calls in a similar way to how you would use the jQuery $.ajax method.
The following code example shows how to use the cross-domain library to access SharePoint task list data
from an external domain:
Using the Cross-Domain Library

'use strict';
Contoso.CDL = function () {
getTasks = function () {
var appweb = // get URL of app web, for example from a query string parameter.
var executor = new SP.RequestExecutor(appweb);
executor.executeAsync(
{
url: appweb +
"/_api/SP.AppContextSite(@target)/web/title?@target='" + hostWebUrl + "'",
method: "GET",
headers: {"Accept": "application/json;odata=verbose"},
success: onSuccess,
error: onError
}
)
},
onSuccess = function (data) {

// Render the returned data.
},
onError = function (data, errorCode, errorMessage) {

// Handle the error.
},
return {
GetTasks: getTasks
}
} ();
Contoso.CDL.GetTasks;
});
The cross-domain library works by using a SharePoint page named AppWebProxy.aspx, which SharePoint
exposes on every site through the LAYOUTS directory. Essentially, the SP.RequestExecutor object creates a
hidden iFrame in the remote web page and loads the AppWebProxy page. It passes the query operations
to the AppWebProxy page in the iFrame, which in turn executes the commands against the app web.
The Web Proxy

The web proxy enables you to call RESTful web services in external domains from JavaScript running in an
app web page. It does this by routing the web service call through the SharePoint server. A proxy on the
SharePoint server makes the call to the external service and returns the response to the app web page.
You access the web proxy by using the SP.WebRequestInfo object, which is included in the sp.js library.
Before you can use the web proxy, you must register the domain of the external service as a trusted
domain in the app manifest file. For example, suppose you want to use a stock pricing service provided by
a partner organization, Northwind Traders. Northwind exposes the service at the URL
http://northwindtraders.com/stock/feed/. Your first task would be to use a RemoteEndpoint element
to register the northwindtraders.com domain as trusted in the app manifest file:
<RemoteEndpoints>
<RemoteEndpoint Url="http://northwindtraders.com" />
</RemoteEndpoints>
When you have registered the domain in the app manifest file, you can then use the web proxy to call the
service from pages in your app.
The following code example shows how to use the web proxy to call a RESTful web service from a web
page:
Using the Web Proxy

'use strict';

Contoso.ResponseDocument;
Contoso.StockProxy = function () {
getData = function () {
var context = SP.ClientContext.get_current();
var proxyRequest = new SP.WebRequestInfo();
proxyRequest.set_url("http://northwindtraders.com/stock/feed/getByClient('Contoso')");
proxyRequest.set_method("GET");
window.Contoso.ResponseDocument = SP.WebProxy.invoke(context, request);
},
onSuccess = function (data) {

var xmlResponse = $.parseXML(window.Contoso.ResponseDocument.get_body());
// Parse the XML body and render the stock prices.
},
onError = function (errorMessage) {

alert(JSON.stringify(errorMessage));
},
return {
GetData: getData
}
} ();
Contoso.StockProxy.GetData();
});
Lesson 4
Designing Apps for Performance
Because apps for SharePoint are not permitted to run any code on SharePoint servers, app developers can
often be less concerned about how their code impacts the performance of the SharePoint environment.
However, performance and efficiency are still important. Executing queries from client-side code adds to
the demand for server-side resources, and you should avoid overloading servers that are already
experiencing high load. At the same time, you can optimize the user experience by ensuring that your
calls to the server are efficient and minimal. In this lesson, you will learn about a range of techniques that
you can use to improve the performance of apps for SharePoint.
Lesson Objectives
 Retrieve and interpret SharePoint health scores.

 Maximize your use of client-side caching.
 Use batching and filtering to optimize calls to the server.
Using SharePoint Health Scores

SharePoint 2013 maintains a health score for every
web application and every server in a server farm.
The health score is an integer value between 0 and
10, where 0 represents a healthy web application
under very little load and 10 represents an
overloaded web application. SharePoint calculates
these health scores based on various factors, such
as the amount of memory available and the
number of concurrent requests. If the health score
reaches 10, SharePoint will start throttling requests
and clients will receive an HTTP 503: Service
Unavailable response. By default, SharePoint
updates health scores every five seconds.
When you develop apps for SharePoint (or any other application that sends requests to SharePoint), a
good practice is to check the server health score before you submit any performance-intensive
operations. SharePoint makes health scores available to clients by including a header named X-
SharePointHealthScore in every HTTP response.
The following code example shows how to retrieve the health score of a SharePoint web application by
using JavaScript and jQuery:
Retrieving the SharePoint Health Score

var getScore = function () {
$.ajax({
type: "HEAD",
url: _spPageContextInfo.webServerRelativeUrl + "/_layouts/15/blank.htm",
success: function (data, status, xhr) {
alert(xhr.getResponseHeader("X-SharePointHealthScore"));
}
});
}
Notice that in this example we request the blank.htm page from the LAYOUTS folder. You can retrieve the
health score by sending an HTTP GET request or an HTTP HEAD request for any SharePoint resource. The
blank.htm page was chosen because it is very small, it does not need to be compiled by the server, and it
is available on every site through the _layouts virtual directory.
Using Client-Side Caching

One of the key principles behind designing
responsive web pages is to minimize the amount of
data that you exchange with the server. One way
you can do this is by maximizing your use of the
browser cache.
When you use the JavaScript object model or the
REST API to send queries to the server, the browser
will cache responses to HTTP GET requests
automatically. (Responses for other HTTP verbs,
such as POST, PUT, MERGE, and DELETE, are never
cached.) For example, suppose you send a GET
request to the REST API at the following URL:
http://team.contoso.com/_api/lists/getByTitle('Invoices')/items
The first time your app sends this request, the query is sent to the server. The server responds by
providing a list of items from the Invoices list in JavaScript Object Notation (JSON) format. If the app
sends the same GET request again, the server sends a HTTP 304 (Not Modified) response. This means that
the data has not changed since the last time the browser sent the request, and the browser should
retrieve the data from its local cache.
The following screen capture illustrates how the browser uses a local cache to store responses to AJAX
requests. In this example, an app for SharePoint uses the jQuery ajax method to request a page every five
seconds. On the first request, the server sends an HTTP 200 response that includes the requested page. On
all subsequent requests, the server sends an HTTP 304 response that indicates that the browser already
has the current version of the page.
FIGURE 1.1: BROWSER-BASED CACHING OF AJAX REQUESTS

One way to minimize the load on the server, and to maximize the use of the browser cache, is to use a
content delivery network (CDN). A CDN is a cloud-based server farm from which end users can download
frequently used files, such as script libraries. Many large companies provide CDNs, either as a subscription
service or as a way of supporting their own products. Microsoft provides a Microsoft Ajax CDN and a
Windows Azure CDN. For example, you can obtain the jQuery library from the following URL, provided by
the Microsoft Ajax CDN:
http://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.js
This approach provides two key benefits. First, it reduces the load on the SharePoint server (or the remote
web server, in the case of provider-hosted apps), because you no longer need to host or serve the jQuery
library. Second, because many websites share the same CDNs, the jQuery library is more likely to be in the
browser cache already, which further reduces load times.
If you subscribe to a CDN provider, such as the Windows Azure CDN, you can use the CDN to serve your
own static content, such as binary large objects (BLOBs) and CSS files. CDNs typically provide a globally
distributed hosting platform, which means that end users should experience fast load times regardless of
their geographical location.
Optimizing Server Requests

When you develop an app for SharePoint, any
communication with the server takes place through
the client.svc web service. As such, design
guidelines and good practices for web service
clients in general also apply to apps for SharePoint.
In particular, you should:
 Minimize the amount of data that you exchange

with the server. You can achieve this by
structuring queries so that result sets are
filtered on the server before being returned to
the client.
 Minimize the number of round trips to the

server. You can achieve this by batching requests.
Minimizing Bandwidth Requirements

SharePoint objects, such as sites, webs, and list items, often include large amounts of metadata. Retrieving
these objects from client-side code generates a corresponding large amount of network traffic from the
server to the client. To mitigate this problem and to reduce your bandwidth consumption, the SharePoint
2013 client-side object models enable you to specify the property values you want when you request an
object from the server. The object returned from the server will only include values for the properties that
you have requested explicitly, which can substantially reduce the size of the response.
If you are using the managed client object model, you can use lambda expressions to specify the
properties that you want to retrieve:
Specifying Properties with the Managed Client Object Model

ClientContext context = new ClientContext("http://team.contoso.com");
var web = context.Web;
// Retrieve only the Title and Description properties of the Web object.
context.Load(web, w => w.Title, w => w.Description);
// Use the Title and Description properties.

labelTitle.Text = web.Title;
labelDescription.Text = web.Description;
When you use this approach, your code will throw a null reference exception if you attempt to use the
values of any properties other than those that you have explicitly requested.
If you are using the JavaScript object model, you can specify the properties that you want to retrieve as
string arguments in the load method:
Specifying Properties with the JavaScript Object Model

function getWebProperties () {
this.teamWeb = context.get_web();
// Retrieve only the Title and Description properties of the Web object.
context.load(this.teamWeb, 'Title', 'Description');
context.executeQueryAsync(onGetPropertiesSucceeded, onGetPropertiesFailed);
}
function onGetPropertiesSucceeded (sender, args) {

alert('Title: ' + this.teamWeb.get_title());
alert('Description: ' + this.teamWeb.get_description());
}
function onGetPropertiesFailed (sender, args) {

// Handle the exception.
}
When you use the REST API to retrieve data, you can use OData operators to specify the properties you
want to retrieve and to apply filters to the data. Any filters that you specify are applied on the server, so
that the server returns the filtered data to the client, rather than the entire data set. For example, suppose
you have a document library that contains invoices on your SharePoint site. You might want to retrieve
the Customer and Amount fields for every item in which the Status field has a value of Outstanding.
Rather than retrieving every item and performing filtering on the client, you can build the filters into the
query URL such that only relevant data is returned:
http://team.contoso.com/_api/web/lists/getbytitle('Invoices')/items$select=C
ustomer,Amount&filter=Status eq 'Outstanding'
If you use collaborative application markup language (CAML) queries to retrieve list items, you can specify
properties and include filtering as part of the CAML expression. When you do this, the filtering takes place
on the server and you are thereby reducing the amount of data you return to the client.
Batching Requests
Both the JavaScript object model and the managed client object model work by sending requests to the
server in batches. Nothing is sent to the server until you call an ExecuteQuery or an ExecuteQueryAsync
method. You can use this behavior to batch several operations into a single request, thereby minimizing
the number of round trips to the server.
The following code example illustrates how you can batch several operations into a single server request:
Batching Operations with the Managed Client Object Model

ClientContext context = new ClientContext("http://team.contoso.com");
Web web = context.Web;
// Get a reference to the Invoices list and the Customers list.

List invoices = web.Lists.GetByTitle("Invoices");
List customers = web.Lists.GetByTitle("Customers");
// Specify that you want to load the title and description of each list.
context.Load(invoices, list => list.Title, list => list.Description);
context.Load(customer, list => list.Title, list => list.Description);
// Execute the query as a single operation.

Using Browser-Based Storage

HTML5 includes a specification named HTML5 Web
Storage that enables web pages to store data in the
user's browser. When it comes to persisting data
over the course of a session, HTML5 Web Storage
has various advantages over cookies:
 Stored data is not sent to the server

automatically with every request.
 You can store large amounts of data (typically

5MB to 25MB, depending on the browser).
 All interactions with the data take place in
client-side code; the server cannot interact with
stored data directly.
HTML5 Web Storage is implemented as two different objects:
 localStorage. You can use this object to store data indefinitely. Data is stored according to origin
(protocol, hostname, and port number) and will not be removed when the window is closed.
 sessionStorage. You can use this object to store data for the duration of a session. Data is stored
according to origin, and also by window. For example, if the user browses your app in two different
windows, the browser will use two different session stores. Any data in session storage is deleted
when the user closes the browser window.
In browsers that support HTML5 Web Storage, the localStorage object and the sessionStorage object
are declared in the global namespace. In both the localStorage object and the sessionStorage object,
data is stored as key-value pairs. You can get and set data by using simple getItem and setItem methods
in JavaScript.
The following code example shows how to store and retrieve data by using HTML5 Web Storage with
JavaScript:
Using HTML5 Web Storage

// Set and get data in session storage.
sessionStorage.setItem('contosoKey', 'This item is specific to both the origin and the
browser window');
alert(sessionStorage.getItem('contosoKey'));
// Set and get data in local storage.

localStorage.setItem('contosoKey', 'This item is specific to the origin but shared by all
browser windows and sessions');
alert(localStorage.getItem('contosoKey'));
Lab: Monitoring SharePoint Health Scores

Scenario
The IT team at Contoso has released new performance and design guidelines for SharePoint app
developers. One of the guidelines is that all apps should request a health score from the SharePoint server
before attempting to perform any processing. As the lead SharePoint developer, your task is to create a
reference app that demonstrates how to work with health scores. Within your app, you will use an app
part to poll the server periodically and display a graphical representation of the current health score.
Objectives
After completing this lab, you will be able to:
 Create and deploy an app part.
 Retrieve SharePoint health scores from client-side code.
Lab Setup
Estimated Time: 60 minutes
 Virtual Machine: 20489B-LON-SP-01
A warm-up script named WarmUp.ps1 runs automatically when you start the virtual machine. This script
helps to improve the performance of the virtual machine by downloading the home page of the root site
in each site collection on the server. Occasionally this script displays timeout errors; you can ignore these
errors. You should ensure this script has finished running before you start the lab.
Exercise 1: Creating and Deploying an App Part

Scenario
In this exercise, you will create and configure an app part. You will add support for the jQuery UI library,
and you will create a user interface capable of providing a visual indication of SharePoint server health
scores. Finally, you will test the app part by using a placeholder value for the server health score.
The main tasks for this exercise are as follows:
1. Create a New App for SharePoint.
2. Add an App Part.
3. Add Support for jQuery UI.
4. Create the User Interface.
5. Add a Custom Script File.
6. Test the App Part.
 Task 1: Create a New App for SharePoint

1. Start the 20489B-LON-SP-01 virtual machine.
2. Log on to the LONDON machine as CONTOSO\Administrator with password Pa$$w0rd.
3. In Visual Studio 2012, create a new project with the following settings:
a. Use the App for SharePoint 2013 project template.
b. Name the project SharePointHealthScores.
c. Create the project in the E:\Labfiles\Starter folder.
4. In the New app for SharePoint dialog box, configure the app with the following settings:
5. Name the app SharePoint Health Scores.
6. Use the site at http://dev.contoso.com for debugging.
7. Use the SharePoint-hosted hosting model.
 Task 2: Add an App Part

1. Add an app part named HealthScoresWebPart to the project. When prompted, ensure that you
create a new client web part page for the app part.
Note: The Visual Studio 2012 template for an app part is named Client Web Part (Host
Web).
2. Open the element manifest file for the app part.
3. Set the title of the app part to SharePoint Health Scores.
4. Set the description of the app part to Displays the current health score for the SharePoint web
application.
5. Set the default height of the app part to 120.
6. Save your changes and close the element manifest file.
 Task 3: Add Support for jQuery UI

1. Add the jquery-ui.js file from the E:\Labfiles\Starter\Scripts folder to the Scripts folder in the
project.
2. Add a new Module named SiteAssets to the project.
3. Delete the Sample.txt file from the SiteAssets folder in the project.
4. Add the jquery-ui.css file from the E:\Labfiles\Starter\CSS folder to the SiteAssets folder in the
project.
5. Add a new folder named Images to the SiteAssets folder.
6. Add all the image files from the E:\Labfiles\Starter\CSS\Images folder to the Images folder in the
project.
 Task 4: Create the User Interface

1. Open the HealthScoresWebPart.aspx page.
2. Within the head element, use a link element to reference the style sheet at the project-relative URL
../SiteAssets/jquery-ui.css.
3. Use a script element to reference the JavaScript file at the project-relative URL ../Scripts/jquery-
ui.js.
Note: Because jQuery UI depends on jQuery, ensure that the script element that loads
jquery-ui.js occurs after the script element that loads jquery-1.7.1.min.js.
4. Within the body element, add a p element with an id value of healthPara.
5. Set the text of the p element to Click Start Polling to poll the server for health scores.
6. Add a div element with an id value of healthBar.
7. Add a line break.
8. Add a button element with the text Start Polling.
9. Add a button element with the text Stop Polling.
10. Save your work.
 Task 5: Add a Custom Script File

1. In Solution Explorer, add a new script file named HealthScores.js to the Scripts folder.
2. Configure the script file to use strict JavaScript.
3. Create an anonymous function that executes when the document object model (DOM) is ready.
4. Within your anonymous function, perform the following tasks:

a. Call the jQuery button method on elements of type button.
b. Call the jQuery progressbar method on the element with an id value of healthBar.
c. Set the maximum value of the progress bar to 10 and the current value to 5.
d. Set the text of the healthPara paragraph to Current health score: 5.
5. Save your work.
6. In the HealthScoresWebPart.aspx page, add a script tag to reference the HealthScores.js file.
7. Save your work.
 Task 6: Test the App Part

1. Start debugging the project. If you are prompted for credentials, log in as CONTOSO\Administrator
with password Pa$$w0rd.
2. In Internet Explorer, when the page has finished loading, click Contoso Development Site.
3. On the Contoso Development Site home page, remove the Get started with Apps for Office and
SharePoint web part from the page.
4. Add the SharePoint Health Scores app part to the page.
5. Save your changes to the page.
6. Verify that the SharePoint Health Scores web part displays:

a. A paragraph with the text Current health score: 5.
b. A progress bar with a gray fill color to the midway point.
7. Close Internet Explorer.
Results: After completing this exercise, you should have created, configured, and deployed an app part.
Exercise 2: Working with Server Health Scores

Scenario
In this exercise, you will configure your app part to retrieve the current health score from the SharePoint
server every five seconds. You will display a text value for the health score, and you will represent the
health score graphically as a value on a progress bar.
1. Use the Revealing Module Pattern to Structure the JavaScript code.
2. Add Health Score Polling Functionality.
3. Connect the Start Polling and Stop Polling buttons.
4. Test the App Part.
 Task 1: Use the Revealing Module Pattern to Structure the JavaScript code
1. In the HealthScores.js file, delete everything except the use strict declaration.
2. Declare a new custom namespace named Contoso.
3. Within the Contoso namespace, create a member named HealthScores and set it to a self-executing
anonymous function. All subsequent code should be created within this anonymous function.
4. At the top of the anonymous function, call the jQuery button method on elements of type button.
5. Declare a variable named healthScore. You will use this variable to store the latest health score from
the server.
6. Declare a variable named pollInterval. You will use this variable to provide a handle for JavaScript
timing functions.
7. Declare a variable named getHealthScore, and set it to an anonymous function.
8. Declare a variable named startPolling, and set it to an anonymous function.
9. Declare a variable named stopPolling, and set it to an anonymous function.

10. Add a return statement.
11. Within the return statement, return the startPolling variable as StartPolling.
12. Return the stopPolling variable as StopPolling.
13. Save your work.
 Task 2: Add Health Score Polling Functionality

1. Within the function associated with the getHealthScore variable, call the jQuery ajax method.
2. Configure the ajax method to submit a HEAD request to the URL at _layouts/15/blank.htm.
3. Add a success handler to the ajax method.
4. Within the success handler, perform the following tasks:
a. Set the healthScore variable to the value of the X-SharePointHealthScore header provided by
the server.
b. Set the text of the healthPara paragraph to Server health score: plus the value of the
healthScore variable.
c. Use the jQuery progressbar method to set the value of the healthBar progress bar to the value
of the healthScore variable.
5. Within the function associated with the startPolling variable, use the jQuery progressbar method to
initialize the healthBar element as a progress bar.
6. Set the maximum value of the progress bar to 10, and the initial value to 0.
7. Call the getHealthScore function.
8. Use a JavaScript timing function to call the getHealthScore function every five seconds. Use the
pollInterval variable to store the handle for the timer.
9. Within the function associated with the stopPolling variable, clear the timer that calls the
getHealthScore function.
10. Set the text of the healthPara paragraph back to its original value of Click Start Polling to poll the
server for health scores.
11. Destroy the progress bar.

12. Save your work.
 Task 3: Connect the Start Polling and Stop Polling buttons

1. Open the HealthScoresWebPart.aspx page.
2. Locate the button element that displays the text Start Polling.
3. Configure the click event handler for the button to call the Contoso.HealthScores.StartPolling
function.
4. Locate the button element that displays the text Stop Polling.
5. Configure the click event handler for the button to call the Contoso.HealthScores.StopPolling
function.
6. Save your work.

1. Start debugging the project. If you are prompted for credentials, log in as CONTOSO\Administrator
with password Pa$$w0rd.
3. On the Contoso Development Site home page, on the SharePoint Health Scores web part, click
Start Polling.
4. Verify that the web part displays a server health score and a progress bar indicator.
Note: The health score is likely to remain static at 0 at this point, as the server is under very little
load.
5. Without closing Internet Explorer, open a File Explorer window and browse to E:\Labfiles\Starter.
6. Right-click LoadWebServer.ps1, and then click Run With PowerShell.
Note: If the PowerShell window displays an Execution Policy Change message, type Y,
and then press Enter.
7. Switch back to Internet Explorer, and verify that the web part displays an increased server health
score.
Note: It may take several seconds before the increase in load is reflected by the health score.
8. Click Stop Polling, and verify that the progress bar is removed from the web part.
Results: After completing this exercise, you should have configured an app part to poll the server for
health scores.
Module Review and Takeaways

In this module, you reviewed some of the core concepts behind apps for SharePoint. You reviewed the
capabilities of apps for SharePoint, the packaging process, and the infrastructure required to support
apps. You looked at core development techniques for using the REST API, the JavaScript object model,
and the managed client object model. You reviewed the authentication and authorization process, and
looked at how to work with permissions and security tokens in your apps. Finally, you learned some
techniques and good practices for developing robust and efficient apps for SharePoint.
Review Question(s)
Question: Which two service applications must be installed on a SharePoint 2013 server farm
before you can deploy and use apps for SharePoint?
Verify the correctness of the statement by placing a mark in the column to the right.
Statement Answer
True or false: the REST API supports only

CRUDQ data operations.
Question: When you install an app for SharePoint, you must grant it all of the permissions it
requests or cancel the installation. Why does SharePoint not allow you to grant permissions
selectively to apps?
Question: When you develop an app for SharePoint, at what points in your code should you
consider requesting a health score from the SharePoint server?
2-1
Module 2
Developing Managed Metadata Solutions
Contents:
Module Overview 2-1
Lesson 1: Understanding Managed Metadata 2-2
Lesson 2: Configuring Managed Metadata Term Sets 2-9
Lab A: Developing Managed Metadata Solutions (Part 1) 2-19
Lesson 3: Working with Managed Metadata Fields 2-26
Lab B: Developing Managed Metadata Solutions (Part 2) 2-32
Module Overview
Microsoft® SharePoint® 2013 manages content, and a company's content can become extremely large
and difficult to manage. A flexible and consistent system that enables users to label and categorize
content consistently makes a large corpus of content much easier to navigate, search, follow, and present
to browsers. The SharePoint managed metadata features provide such a labeling system. Managed
metadata consists of a centrally managed set of terms and keywords that users can apply to items,
documents, and assets to describe them. The values of managed metadata fields help users to locate and
understand the huge quantity of content that can be available. SharePoint uses the values of managed
metadata fields in many other features, including search, web publishing, enterprise content
management, and social networking feeds.
Objectives
 Explain the capabilities and applications of managed metadata in SharePoint 2013.
 Automate the creation and configuration of managed metadata term sets.
 Interact with managed metadata term sets and fields from client-side and server-side code.
2-2 Developing Managed Metadata Solutions
Lesson 1
Understanding Managed Metadata
Before you can write code that works with managed metadata, you must understand the components of
the managed metadata system as well as the objects that appear in the managed metadata hierarchy. The
Managed Metadata service application provides a centralized database of managed metadata terms and
keywords that can be re-used throughout the SharePoint farm. The service application can store a
hierarchy of terms in a term store. In this lesson you will see all these objects and how they are used to
categorize items so that, in subsequent lessons, you can understand how to work with them in code.
Lesson Objectives
 Describe how managed metadata helps users to label and categorize content consistently.
 Describe the SharePoint components that implement managed metadata functionality.

 List the hierarchy of objects that appear in a term store.
 Describe how to label and re-use terms in term sets.
 Configure permissions and stakeholders in term sets.
Overview of Managed Metadata

SharePoint's managed metadata features provide a
system of hierarchical terms and keywords, which
can be created by administrators or users and
applied to any item, document, or asset in the
SharePoint content database. Tagging content with
metadata helps to categorize and classify items.
Metadata values describe items to users and can be
indexed to help in locating content for search and
enterprise content management.
You should encourage your users to tag item in

order to organize the content of a SharePoint farm.
There are significant advantages to providing them
with a standardized set of terms to choose from:
 You encourage users to choose the same terms rather than synonyms, which can confuse the
categorization. For example, if you provide the term "Cake", you discourage users from tagging with
the synonym "Bun". Users searching for "Cake" would not receive results tagged with "Bun", even
though these results are relevant to the search.
 You can re-use the same terms in multiple hierarchies. For example, the term "Cake" may appear
under the term "Food". Simultaneously the term "Cake" can appear under the term "Product Types".
 Spelling mistakes are less likely, because most users choose from pre-existing terms rather than
creating a new term.
 You can use terms to provide a categorization of content that is independent of the site, list, library,
or folder that contains the content.
Terms, Keywords, and Hashtags

The managed metadata service provides three different types of value:
 Terms. Terms are organized into hierarchies called term sets. Each term can have child terms. For
example, the term "Bike" may have child terms "Racing Bike" and "Mountain Bike". The terms in a
term set are usually managed by a restricted group of users. These may be administrators or power
users. Terms provide a preconfigured taxonomy of content with which to tag items.
 Keywords. Keywords are similar to terms but are not stored in a hierarchy. Any user can create a new
keyword and use it to tag content. Once a keyword exists, other users can choose it to tag their items.
Keywords provide a more dynamic way to tag items, which any user can expand. If a keyword
becomes widely used, a term set contributor can add it to a term set to make it part of the
preconfigured taxonomy.
 Hashtags. SharePoint 2013 is the first version of SharePoint to support hashtags. These tags enable
users to categorize items by typing a tag such as #Cake instead of choosing from a term set or
keywords. This is a very immediate way to create tags and is familiar to many users from social
networking. You can choose to follow hashtags in your user profile.
Using Managed Metadata Fields

Once you have created a set of terms or keywords, you must use them to tag items. In order to do this,
you must use a managed metadata field. A managed metadata field is a type of field that you can add to
a list or library in a SharePoint site. When users edit a managed metadata field they can either choose an
existing term or keyword or they can create a new keyword. You can also add a managed metadata field
to a content type, just like other types of field such as text fields or choice fields.
Managed metadata fields can be single-valued or multi-valued. If a field is single-valued, the user can
apply only one term or keyword to the item. If a field is multi-valued, the user can tag the item with as
many terms or keywords as necessary.
The tag cloud web part is a helpful way to enable users to access content that is tagged. The web part
displays all the tags that have been used in the local site. The size of each tag in the web part indicates
how often a tag has been used; popular tags are displayed in a larger font.
Managed Metadata in Other SharePoint Services

It is essential to understand managed metadata in SharePoint because it underpins many other services
and features. For example:
 In Search. Managed metadata terms can be indexed and used to improve search results. Managed
metadata fields can be used to provide refinements. These help users to refine generalized searches
and obtain the content that they seek.
 In Web Publishing. In SharePoint 2013 you can create a web site navigation hierarchy that is based on
the managed metadata terms applied to each web page. In this way, you can create a site structure
that is independent of the lists, libraries, and folders in your site.
 In Enterprise Content Management. You can use managed metadata fields to create document sets,
which can be declared as a single record and locked.
 In Social Networking. By following a term or keyword, you can keep track of all the activity in the
organization on a subject that interests you.
You will learn more about the way managed metadata enables other SharePoint features in subsequent
modules in this course.
The Managed Metadata Service Application

The most important component in delivering
managed metadata to users is the Managed
Metadata service application. This service can be
used to publish a single term store for all users in
the SharePoint farm or to publish several different
term stores for different SharePoint site collections.
The Managed Metadata Service

Application
Service applications in SharePoint 2013 are
independent of the SharePoint web applications
that store content. Administrators can set up one or
more instances of the Managed Metadata service
application and connect to those instances from web applications. All SharePoint sites in the connected
web applications in this way gain access to the terms contained in the Managed Metadata service
application.
Often, administrators create a single Managed Metadata service application for all web applications in the
farm. However SharePoint developers should bear in mind that sometimes there may be multiple
instances of the service application in the farm and that access to a particular instance may be restricted.
The Managed Metadata service application can also be used to share content types between site
collections. When you create a content type in a SharePoint site, it is usually only available within the
same site. However, by publishing the content type to the Managed Metadata service application, you can
re-use a single content type in many different sites and site collections in your farm. When you configure
a Managed Metadata service application instance, you can designate a site collection as the Content Type
Hub for the service application. The service application will then propagate content types and site
columns from the hub site collections to any other site collections that subscribe to the service application
proxy.
The Managed Metadata service application uses a database to store terms, keywords, and other
information. This database is named when an administrator creates the service application and may be
located on the server that runs the Managed Metadata web service or on a dedicated SQL Server® that
hosts other SharePoint databases such as the content database.
Finally, the Managed Metadata service application requires that the Managed Metadata web service is
running on at least one SharePoint server in the SharePoint farm.
Configuring the Managed Metadata Service Application

In a production SharePoint farm, administrators and not developers usually configure service applications.
However, in the development environment, for example, it may be necessary for developers to configure
the Managed Metadata service application by using the following procedures.
To start the Managed Metadata web service:
1. In Central Administration, under System Settings, click Manage services on server.
2. Next to the Managed Metadata Web Service, click Start.

Alternatively, you can start the Managed Metadata Web Service by running the following commands in
PowerShell:
Starting the Managed Metadata Web Service in PowerShell

#Load the SharePoint snap-in
Add-PSSnapin "Microsoft.SharePoint.PowerShell"
#Get the Managed Metadata Web Service

$metadataWebService = (Get-SPServiceInstance | ?{$_.TypeName –eq "Managed Metadata Web
Service"})
$metadataWebService | Start-SPServiceInstance
To create an instance of the Managed Metadata Service Application and a proxy for the service
application:
1. In Central Administration, under Application Management, click Manage Service Applications.
2. In the ribbon, click New, and then click Managed Metadata Service.
3. In the Name box, type a name for the new service application.
4. In the Database Service box, type the name of the server that will host the managed metadata
database.
5. In the Database Name box, type a name for the new database.
6. Under Application Pool, select or create a new application pool for the service application.
7. Click OK.
Alternatively, you can create an instance of the service application and a proxy by running the following
commands in PowerShell:
Creating a Managed Metadata Service Application in PowerShell

#Get the application pool
$serviceAppPool = Get-SPServiceApplicationPool "SharepointServicesPool"
#Create the metadata service application

$metaDataServiceApp = New-SPMetadataServiceApplication –Name "Managed Metadata Service
Application" –ApplicationPool $serviceAppPool –DatabaseServer "LONDON" –DatabaseName
"MetadataServiceDB"
#Create proxy
New-SPMetadataServiceApplicationProxy –Name "Managed Metadata Service Application Proxy"
–ServiceApplication $metaDataServiceApp –DefaultProxyGroup
Term Store Hierarchy

In addition to terms, there are a number of other
types of object that you must understand in order
to create or use terms programmatically.
Term Stores
A term store represents an instance of the Managed
Metadata service application proxy. For each term
store, you can specify term store administrators
who can create groups in the term store and
determine the managers of each group. You can
also specify the languages of the terms in the term
store.
The Term Store Management Tool is a graphical user interface that you can use to manage groups, term
sets, and terms within a term store. To access the management tool:
1. In Central Administration, under Application Management, click Manage service applications.
2. Click the managed metadata service application, and then click Manage.
Groups
You can use groups as administrative boundaries within the term store to govern which users can
contribute terms to each term set. You can create multiple groups within each term store. Two user roles
are important for each group:
 Contributors. These users have permission to create new terms and term sets in the group.
 Group Managers. These users have contributor permissions, but can also add other users to the
Contributors role.
Place term sets into a single group if the same set of uses should be able to manage terms in those term
sets.
Term Sets
Each term set contains a single hierarchy of terms. For each term set, you can set the submissions policy. If
the submissions policy is Open, any user can add terms. If the policy is Closed only group contributors can
add terms.
Three user roles are important for each term set:
 Owner. The term set owner is informational only. The term set owner is not granted any specific
permissions by virtue of being the term set owner.
 Contact. The contact is not a user account but an email address. Users without contributor
permissions can send a message to this address to ask for new terms and other changes. The contact
email address is often the email address of the term set owner account.
 Stakeholders. A stakeholder is a user who has an interest in the term set. Stakeholders are notified
when contributors make changes to the term set. For example, if a term set is used for navigation in a
web publishing site, the stakeholders should include the web site designers.
Within each term set, anyone with contribute permissions can create individual terms. You can create up
to seven nested levels of terms. You will learn more about terms in the next topic.
Understanding Terms
A managed metadata term is more than a single
word. It has a number of properties and actions that
you can use to manage its behavior.
Using Labels For Languages and

Synonyms
You can use labels to enable SharePoint to help the
user choose an appropriate term. For example,
consider the term "Bike". If the user types "Bicycle"
into a managed metadata field, you would like
SharePoint to suggest they tag the item with the
term "Bike". You can use labels to enable this
behavior.
When you create a term, SharePoint sets the default label to match the term name. This is the label that is
displayed to users when an item is tagged with this term. It is also the value that is stored in the managed
metadata field for the item. You can use the Other Labels property to add any number of synonyms and
abbreviations.
Labels support multiple languages for each term. You can configure each term set to support multiple
languages. For each supported language you can specify a different set of labels for each term. For
example, in English, the default label for the "Bike" term may be "Bike" and other labels may include
"Bicycle". In French, the default label for the "Bike" term may be "Velo" and other labels may include
"Bicyclette".
Copying, Reusing, and Pinning Terms

You may need to use the same term is multiple term sets. For example, the "Camera" term may be
required in both the "Products" term set and in the "Technical Documents" term set. You can duplicate
terms in four different ways.
 Copy. When you copy a term, you create a sibling term with the same labels and other properties.
You can edit the copied term independently of the source term and move it to other locations in the
term store.
 Copy with Children. When you copy a term with children, the copied sibling term includes the entire
sub-hierarchy of the source term. The sub terms can be edited independently.
 Re-use. When you re-use a term, you make the same term appear at different locations in the term
store. However, there is only one term. If you change the properties of the re-used term in, one
location, your changes also apply to the other locations where the term appears. When you re-use a
term, child terms are not re-used and changes can be made wherever the term appears.
 Pin with Children. As with re-using labels, when you pin a term, you make the same term appear at
different locations in the term store. However, changes can only be made in one location where the
term is pinned. Also, the child terms of a pinned term appear in both locations.
Custom Properties
You can associate custom properties with term sets and terms. Custom properties essentially enable you
to specify your own metadata with term sets and terms, typically for use in code-based solutions. You can
set custom properties in the term store management tool or programmatically.
Availability and Deprecation

Each term, by default, is available for tagging. This means that users can apply the term to an item,
document, or asset in the SharePoint content database. However, you can choose to make a term
unavailable for tagging so that a term cannot be applied to items. You can use this technique if a term is
intended to organize a term set rather than apply to items. For example, if you create a term set for users
to apply to products, you may not want users to apply the term "Accessories" to items. Instead the
"Accessories" term helps users to navigate the term set and find child terms such as "Flight Cases" and
"Power Supplies".
You can also deprecate terms when you no longer want them to be applied to items. Users cannot add a
tag with a deprecated term, but existing items can keep the deprecated term if it already applied. Users
also cannot copy, re-use, pin, or create child terms for deprecated terms.
Discussion: Using Terms

Discuss the following scenarios with the class. In
each case, decide how you might create and use
groups, term sets, and terms to satisfy the
requirements. Consider in each case whether to use
labels, re-used terms, copied terms, or pinned
terms. Also consider which users should take which
roles in the Managed Metadata hierarchy.
Categorizing Products
You have products stored in several different
SharePoint sites in a single site collection. All the
product lists use the Product content type. You
want to enable users to categorize products
according to a set of categories provided by product managers. The key requirements are as follows:
 The product category hierarchy consists of three levels: Department, Category, and Subcategory.
 When users tag a product, they must select a tag at the Subcategory level. In other words, to prevent
orphaned objects, a user should not be able to specify a department or a category without specifying
a subcategory.
 Only members of the Product Managers group should be able to alter the terms and structure of the
product category hierarchy.
 The product category hierarchy is expected to change every so often, but old items may remain in the
catalog if they prove popular.
Improving Search Results

You have a large corpus of documents throughout your SharePoint farm. You want to encourage users to
tag all documents with a consistent set of terms in order to improve the relevance of search results. You
decide to implement three term sets:
 Hot Topics. This includes terms that describe industry trends, and is intended for users to highlight
documents that address those subjects.
 Technical Areas. This includes terms that describe engineering topics and is intended to help technical
staff find answers to technical questions.
 Marketing. This includes terms that describe marketing campaigns and the subjects they promote.
Terms from Hot Topics may be relevant to marketing campaigns and technical staff. Technical terms may
be relevant to all users, but should only be changed by technical staff.
Lesson 2
Configuring Managed Metadata Term Sets
Now that you understand how managed metadata works, you can learn how to manipulate managed
metadata in code. The SharePoint APIs enable developers to access groups, term sets, terms, and other
metadata objects from managed code or script. Using these APIs, desktop applications, SharePoint
solutions, and SharePoint apps can read and write information to the managed metadata hierarchy. In this
lesson, you will see how to build a term set by writing code that creates groups, term sets, and terms. You
will also see how to use the advanced features of terms and manage permissions and roles. In this way
you can provide a full set of terms with which users can tag content.
Lesson Objectives
 Obtain handles for taxonomy sessions and term stores, through which you can access metadata.
 Write code that reads and creates new groups and term sets.
 Write code that reads and creates new terms in a hierarchy.
 Use the server-side object model to build a complete term set.

 Write code that copies, re-uses, and pins terms in other locations in the hierarchy.
 Write code that manages permissions, roles, and stakeholders.
Obtaining Taxonomy Sessions and Term Stores

Before you can read or change any information in
managed metadata, you must open a taxonomy
session. This is always the first stage in any coded
managed metadata operation. After opening a
session you can access a term store, which contains
groups, term sets, and terms.
To use the SharePoint taxonomy server-side API,

include a reference to the
Microsoft.SharePoint.Taxonomy library in your
project. To use the JavaScript taxonomy API, include
a script link to the sp.taxonomy.js file in your app
or web site. This JavaScript library can be found in
the SharePoint /_layouts/15 web folder.
Opening a Taxonomy Session

To open a taxonomy session, use the constructor on the TaxonomySession object. This constructor
requires you to pass a site collection as a parameter, so you must obtain a site collection first.
The following code shows how to create a TaxonomySession object in C#:
Opening a Taxonomy Session in C#

//Get a site collection
using (SPSite siteCollection = new SPSite("http://dev.contoso.com"))
{
//Pass the site collection to the taxonomy session constructor
TaxonomySession taxonomySession = new TaxonomySession(siteCollection);
}
The following code shows how to create a TaxonomySession object in JavaScript:
Opening a Taxonomy Session in JavaScript

//Get the client context. This method works in SharePoint-hosted apps
//Pass the client context to the taxonomy session constructor

var taxonomySession = SP.Taxonomy.TaxonomySession.getTaxonomySession(context);
//Load the session object

context.load(taxnomySession);
//Execute the query

context.executeQueryAsync(function success () {
alert("Taxonomy session open.");
}, function failure (sender, args) {
alert("Could not open taxonomy session");
});
Opening a Term Store

The TermStore object represents a connection to the Managed Metadata service application. In fact, the
TermStore object connects to the service application proxy, which permits access to the service
application.
The TaxonomySession object includes a collection of all the term stores that exist in the Managed
Metadata service application. You can access a specific term store by providing an index. This can be an
integer, the GUID of the term store, or the name of the term store.
Note: If you use the name to access a specific term store, note that you should use the
name of the Managed Metadata service application proxy. The name of this proxy can differ from
the name of the service application itself.
The following code opens a term store named "Managed Metadata Service Application Proxy" in C#:
Opening a Term Store in C#

//Open the term store
TermStore termStore = taxonomySession.TermStores["Managed Metadata Service Application
Proxy"];
Console.WriteLine("Opened this term store: " + termStore.Name);
The following code opens a term store in JavaScript:

Opening a Term Store in JavaScript

//Get the term store by name
var termStore = taxonomySession.get_termStores().getByName("Managed Metadata Service
Application Proxy");
//Load the term store

context.load(termStore);
//Execute the query

alert("Opened this term store: " + termStore.get_name());
alert("Could not open term store.");
});
Creating Groups and Term Sets

The top-level objects within any term store are the
groups. Each group is an administrative boundary
that determines which users have contributor and
manager permissions within the term sets that the
group contains. Each group can contain one or
more term sets, which you must create or access to
create terms.
Note: In the code examples, notice that when

you make any changes to groups, term sets, or
terms, you should call the TermStore.CommitAll()
method to save your changes to the Managed
Metadata service application database.
Working with Groups

To obtain an existing group you can pass integers, a GUID, or a name to a TermStore.Groups collection.
Alternatively, if you want to create a new group, call the TermStore.CreateGroup() function.
In the following C# example, the code checks that a group named "Vehicles" exists. If the group does not
exist, the code creates a new group:
Accessing or Creating a Group in C#

Group group;
Guid groupGUID = new Guid("2598DF4E-CD31-DAB3-3653-369DAB3C95CA");
try
{
//Get the Vehicles group
group = termStore.Groups["Vehicles"];
}
catch (ArgumentOutOfRangeException)
{
//The Vehicles group does not exist. Create it.
group = termStore.CreateGroup("Vehicles", groupGUID);
//Commit the changes
termStore.CommitAll();
}
In the following JavaScript example, the code checks for a group named "Vehicles" by looping through all
the groups in a term store:
Accessing a Group in JavaScript

var groups;
//Get all the groups in the term store

groups = termStore.get_groups();
context.load(groups);
//Execute the query

context.executeQueryAsync(function success() {
//Use the group enumerator to loop through the groups

var groupEnumerator = groups.getEnumerator();
while (groupEnumerator.moveNext()) {
currentGroup = groupEnumerator.get_current();
if (currentGroup.get_name() == "Vehicles") {
//This is the right group
alert("Loaded group: " + currentGroup.get_name());
}
}
}, function failure(sender, args) {

alert("Could not load groups");
});
In the following JavaScript example, the code creates a new group named "Vehicles":
Creating Groups in JavaScript

var newGroupGUID = "2598DF4E-CD31-DAB3-3653-369DAB3C95CA";
//Create the new group

var vehiclesGroup = termStore.createGroup("Vehicles", newGroupGUID);
//Load the new group

context.load(vehiclesGroup);
//Execute the query

alert("Vehicles group created");
alert("Could not create vehicles group");
});
Working with Term Sets

To obtain an existing term set, you can pass a GUID to the Group.GetTermSet() method. Alternatively, if
you want to create a new group, call the Group.CreateTermSet() function.
The following code example accesses a term set with a specific ID. If the term set does not exist, the code
creates a new term set, named "Cars":
Working with Term Sets in C#

Guid termSetGUID = new Guid("1438D56E-B131-C6B3-7653-369DAB3C10BD");
//Try to obtain the term set

TermSet carsTermSet = vehiclesGroup.GetTermSet(termSetGUID);
if (carsTermSet == null)
{
//There is no term set with the right GUID. Create a new one.
carsTermSet = vehiclesGroup.CreateTermSet("Cars", termSetGUID);

}
Note: Because you cannot run client-side code with elevated permissions, only term store
administrators will be permitted to create, edit, or delete groups, term sets, and terms from
client-side code.
Creating Terms
When you have a TermSet object, you can create a
top-level term by calling the
TermSet.CreateTerm() method. You can create
child terms by calling the Term.CreateTerm()
method. In this way, you can build a hierarchy of
terms.
The CreateTerm() method is defined on the

abstract TermSetItem class. Both TermSet and
Term classes inherit this class. Other methods
inherited from the TermSetItem class include
Delete() and Re-useTerm(), which you will see in a
later topic.
Creating Terms
To create a term in a term set, you must supply three parameters to the CreateTerm() method:
 Name. This string is also used as the default label for the term.
 Locale ID. This integer specifies the language and region for the term.
 GUID. Optionally, you can provide a GUID for the new term. SharePoint assigns a GUID automatically
if you do not supply one. However, if you specify a GUID it is easy to locate the correct term in later
code.
The following C# code illustrates how to create a new term in a term set:
Working with Terms in C#

Guid newTermGUID = new Guid("02639124-4dfa-4174-89d2-4f506f3a5d55");
termSet.CreateTerm("Mini Van", 1033, newTermGUID);
The following JavaScript code illustrates how to create a new term in a term set:
Working with Terms in JavaScript

var newTermGUID = "02639124-4dfa-4174-89d2-4f506f3a5d55";
//Create the new term
var miniVanTerm = termSet.createTerm("Mini Van", 1033, newTermGUID);
//Load the term

context.load(miniVanTerm);
//Execute the query

alert("Term was created successfully");
alert("Could not create new term");
});
Demonstration: Building a Term Set with the Server-Side Object Model

In this demonstration, you will see how to:
 Add references to a console application to work with SharePoint managed metadata.
 Connect to a taxonomy session and open a term store.
 Obtain or create a new group in a term store.

 Obtain or create a new term set in a group.
 Create a new term and commit changes to the term set.
Demonstration Steps
1. Add references to the following namespaces:
o Microsoft.SharePoint
o Microsoft.SharePoint.Taxonomy
2. Add references to the following namespaces to the Program.cs code file:
3. Locate the "Connect to the taxonomy session here" comment and replace it with a line of code that
creates a new TaxonomySession object for the siteCollection.
4. Locate the "Get the term stores here" comment and replace it with a line of code that gets all the
term stores in the taxonomySession object and stores them in a variable named termStores.
5. Locate the "Get the first term store here" comment and replace it with a line of code that gets the first
term store and stores it in a variable named store.
6. Locate the "Get the Vehicles group here" comment and replace it with a line of code that uses the
groupGuid value to obtain the group from the store. Store the group in the vehiclesGroup variable.
7. Locate the "Create a vehicles group here" comment and replace it with a line of code that creates a
new group called Vehicles. Use the following information:
o Method: store.CreateGroup
o Group name: Vehicles
o Group GUID: groupGuid

8. Locate the "Get the Cars term set here" comment and replace it with a line of code that gets a term
set from the store object. Use the following information:
o Method: store.GetTermSet
o GUID: termSetGuid
o Store the term set in a new variable named carsTermSet.
9. Locate the "Create the Cars term set here" comment and replace it with a line of code that creates a
new term set called Cars. Use the following information:
o Method: vehiclesGroup.CreateTermSet
o Term set name: Cars

o Term set GUID: termSetGuid
10. Locate the "Create a term here" comment and replace it with a line of code that creates a new term.
Use the following information:
o Method: carsTermSet.CreateTerm
o Term name: Station Wagon
o LCID: 1033
11. Locate the "Commit the changes to the term store here" comment and replace it with a line of code
that commits all changes to the store object.
12. Run the TermSetCreator project in debugging mode.

13. In Central Administration, open the Managed Metadata Service Application.
14. Verify that the Vehicles group, the Cars term set, and the Station Wagon term have been created as
expected.
15. Close all open applications.
Using Terms
Each term can have multiple labels that are usually
synonyms or abbreviations of the term. Labels
encourage users to use terms consistently because
SharePoint suggests the term when they type a
synonym in a managed metadata field. A single
term can also be re-used in different term sets in a
term store.
Adding Labels to Terms

A term's default label is a string that usually
matches the term's name. However, you can also
add any number of other labels to help users locate
the term in the managed metadata. If you use multiple languages, you can add labels in those languages
to each term so that a single term can be used internationally.
The following code shows how to add a label to a term by using the server-side object model:
Adding a Label to a Term in C#

//Find out about the current UI culture
int cultureID = CultureInfo.CurrentUICulture.LCID;
//Add the new label

Label newLabel = miniVanTerm.CreateLabel("Camper Van", cultureID, false);
//Commit changes
Reusing Terms
In order to re-use a term in another location, you must first get a reference to the source term. Next,
obtain a reference to the parent term in the new location and call the Term.Re-useTerm() method.
The following code shows how to re-use terms in C# server-side code:
Reusing a Term
//Get the source term.
Guid sourceTermGUID = new Guid("220227d7-c26e-4fc0-b0db-2e632bc561f8");
Term sourceTerm = termStore.GetTerm(sourceTermGUID);
//Get the parent term in which to re-use the source term

Guid destinationTermGUID = new Guid("4cea8d06-3913-4f0d-aa32-1680d554df90");
Term destinationTerm = termStore.GetTerm(destinationTermGUID);
//Re-use the source term

Term re-usedTerm = destinationTerm.Re-useTerm(sourceTerm, false);

When you re-use a term in this way, the term can be modified in both locations. In the above code, this
means that changes to the sourceTerm object will automatically apply to the re-usedTerm object.
Pinning a Term
When you re-use a term with pinning, the re-used term, which is the term in the destination, cannot be
modified. The Re-useTermWithPinning() method is similar to the Re-useTerm() method.
The following code shows how to re-use a term with pinning in C#:
Pinning a Term
//Get the source term.
Guid sourceTermGUID = new Guid("220227d7-c26e-4fc0-b0db-2e632bc561f8");
Term sourceTerm = termStore.GetTerm(sourceTermGUID);
//Get the parent term in which to re-use the source term

Guid destinationTermGUID = new Guid("4cea8d06-3913-4f0d-aa32-1680d554df90");
Term destinationTerm = termStore.GetTerm(destinationTermGUID);
//Re-use the source term with pinning

Term re-usedTerm = destinationTerm.Re-useTermWithPinning(sourceTerm);

Managing Permissions and Stakeholders

As you saw in the first module, many of the objects
in a term store hierarchy have user roles associated
with them. You can write code to set these user
roles and manage users' permissions in the
hierarchy.
The TaxonomyRights Enumeration

The TaxonomyRights enumeration includes values
that identify the different permissions that are
possible on different taxonomy objects. You can use
this enumeration to check or set permissions. The
following values are included:
 EditTerm. This value indicates that a user has the right to edit the properties of a term.
 EditTermSet. This value indicates that a user has the right to edit the properties of a term set and can
add new terms.
 EditGroup. This value indicates that a user has the right to edit the properties of a group and can add
new term sets.
 ManageTermStore. This value indicates that a user has the right to add new groups to a term store
and can set permissions for a group.
 Contributor. This value indicates that a user has contributor permissions in a group and can add
terms.
 GroupManager. This value indicates that a user has manager permissions in a group and can add
terms and term sets, as well as grant contributor permissions.
 All. This value indicates that a user has full control on a taxonomy object.
Checking Permissions
Permissions are always enforced, whether you check them in your code or not. However, sometimes you
may want to take actions based on the permissions available to a user. For example, if a user cannot edit a
term, you may want to hide the “Add Label" button.
To check permissions in your code, use the TermSetItem.DoesUserHavePermission method. This
method returns a Boolean value by passing a TaxonomyRights value to indicate if the current user has
the permission you specify.
The following code shows how to check whether a user has contributor rights on a group:
Checking Permissions in C#
//Get the group
if (group.DoesUserHavePermissions(TaxonomyRights.Contributor))
{
Console.WriteLine("The current user is a contributor in the Vehicles group.");
}
else
{
Console.WriteLine("The current user is not a contributor in the Vehicles group.");
}
Adding Contributors and Managers to Groups

If you are a contributor in a group, you have permission to edit terms and term sets within that group. If
you are a group manager, you can also create new term sets in the group and assign contributor
permissions to other users.
The following code shows how to add a contributor and a group manager to a taxonomy group in server-
side code:
Assigning Roles in Groups

//Get the group
//Assign the contributor role to Melissa Kerr

group.AddContributor("CONTOSO\MelissaK");
//Assign the group manage role to Bart Duncan

group.AddGroupManager("CONTOSO\BartD");

Adding Stakeholders to Term Sets

A stakeholder is a user who receives an alert when a major change is applied to a term set. To add a
stakeholder, you can use the TermSet.AddStakeHolder() method.
The following code show how to use the AddStakeHolder() method in server-side code:
//Obtain the term set

Guid termSetGUID = new Guid("1438D56E-B131-C6B3-7653-369DAB3C10BD");
TermSet carsTermSet = vehiclesGroup.GetTermSet(termSetGUID);
//Add the new stakeholder

carsTermSet.AddStakeHolder("CONTOSO\JesseM");

To remove the stakeholder, use the similar TermSet.DeleteStakeHolder() method and pass the same
login name.
Lab A: Developing Managed Metadata Solutions (Part 1)

Scenario
Contoso Pharmaceuticals consists of a number of divisions, each of which contains several teams. Contoso
users increasingly need to capture details of the division and the team as metadata on various types of
content. Your task is to deploy a term set that represents the corporate structure, together with a site
column that enables people to use the term set in lists and libraries. Because Contoso operates a range of
SharePoint 2013 installations and SharePoint Online subscriptions, you will use an app to automate the
deployment of the term set and site column.
Objectives
 Create and configure a new SharePoint-hosted app that works with managed metadata.
 Obtain managed metadata objects such as term stores, groups, and term sets, and display them in a
web page.
 Create managed metadata objects such as groups and term sets, by using the JavaScript CSOM.
Lab Setup
 Username: CONTOSO\Administrator
The app includes no facilities for removing the term set and group that it creates. If, in Exercise 3, you
push the “Create Corporate Term Set” button more than once, an error will be displayed because the term
set and group already exist. If you want to remove the term set and group so that you can execute the
code again, run the following PowerShell script: E:\Labfiles\Scripts\CleanUpTermStore.ps1
Exercise 1: Creating and Configuring the Corporate Structure App

Scenario
To begin building the Corporate Structure App, you will create a new SharePoint-hosted app. To avoid
having to build a JavaScript framework for the app, a skeleton App.js file has been provided, which you
will import. Similarly, to avoid having to build a user interface, ASP.NET markup has been provided. You
will import this into the default.aspx file and add a link to the SharePoint Taxonomy JavaScript CSOM.
1. Create a New SharePoint-Hosted App
2. Import Starting Code
3. Link to the Taxonomy Script Library
4. Configure App Permission Requests

 Task 1: Create a New SharePoint-Hosted App

3. Open Visual Studio® and create a new project. Use the following information:
o Template: App for SharePoint 2013
o Name: CorporateStructureApp
o Location: E:\Labfiles\Starter
4. Use the following information to configure your app:
o Name: Corporate Structure App

o Debugging site: http://dev.contoso.com
o Hosting model: SharePoint-hosted
 Task 2: Import Starting Code

1. Open the following file in Notepad: E:\Labfiles\Starting Code\UIMarkup.txt
2. Copy all the text in the file to the clipboard.
3. In Visual Studio, in the Default.aspx file, locate the div element. Delete the entire contents of the div
element and paste the contents of the clipboard into the empty div element.
4. Delete the App.js file from the Scripts folder.
5. Add the following file to the Scripts folder: E:\Labfiles\Starting Code\App.js
6. Save all your changes.
 Task 3: Link to the Taxonomy Script Library

1. In the Default.aspx file, immediately after the link to the sp.js script, insert a script link to the
sp.taxonomy.js file.
2. Save your changes.
 Task 4: Configure App Permission Requests

1. Add a permission request to the AppManifest.xml file. Use the following information:
o Scope: Taxonomy
o Permission: Write
2. Add a permission request to the AppManifest.xml file. Use the following information:
o Scope: Web
o Permission: Full Control
Results: A new SharePoint hosted app with a JavaScript framework, user interface, and JavaScript library
links is completed.
Exercise 2: Displaying the Existing Taxonomy Groups

Scenario
In this exercise you will write JavaScript code in the App.js file that uses the Taxonomy JavaScript CSOM to
check and display the groups in the term store.
1. Load the Term Store
2. Display the Groups
 Task 1: Load the Term Store

1. In the App.js file, in the loadTermStore function, open a taxonomy session and store it in a variable
named taxonomySession. Use the following information:
o Method: SP.Taxonomy.TaxonomySession.getTaxonomySession()
o SharePoint context: context
2. Obtain the term store and store it in the termStore variable. Use the following information:
o Method: taxonomySession.get_termStores().getByName()
o Term store name: Managed Metadata Service Application Proxy
3. Load the taxonomySession and termStore objects.
4. Call the executeQueryAsync function and pass anonymous functions for successes and failures.
5. In the anonymous function for successes, update the page element with ID status-message to
inform the user that the term store is loaded.
6. Call the checkGroups() function with no parameters.

7. In the anonymous function for failures, update the page element with ID status-message to inform
the user that the term store could not be loaded.
 Task 2: Display the Groups

1. Create a new function named checkGroups.
2. Store all the groups in the termStore object in a new variable named groups.
3. Load the groups object.
5. In the anonymous function for successes, remove all the child elements of the page element with ID
groups-list.
6. Get the enumerator from the groups collection and store it in a variable named groupEnum.
7. Use the groupEnum.moveNext() function to loop through all the groups in a while loop.
8. In the while loop, get the current group from the groupEnum object and store it in a new variable
named currentGroup.
9. Get the ID from the currentGroup object and store it in a new variable named currentGroupID.
10. Create a new <div> element and store it in a new variable named groupDiv.
11. Append a child element to the groupDiv page element. The child element must be a text node that
is the name of the currentGroup object.
12. Append the groupDiv object to the page element with ID groups-list.
13. In the anonymous function for failures, update the page element with ID status-message to inform
the user that groups could not be loaded.
14. Save your changes and then rebuild the solution.
15. Start the app in debugging mode and authenticate with the following credentials:
o Username: Administrator
o Password: Pa$$w0rd
16. Verify that the app displays a single group named System.
Results: A SharePoint-hosted app that can display groups from the Managed Metadata service
application.
Exercise 3: Creating a Group, a Term Set, and Terms

Scenario
In this exercise, you will add code that creates a new group and adds it to the taxonomy term store. You
will also create a new term set within that group.

1. Complete the Create Term Set Function
2. Create Terms in the New Term Set
3. Test the Corporate Structure App
 Task 1: Complete the Create Term Set Function

1. In App.js, in the createTermSet function, set the text of the page element with ID status-message
to Creating the group and term set…
2. Create a new taxonomy group and store it in the corporateGroup variable. Use the following
information:
o Method: termStore.createGroup
o Group name: Corporate Structure
o Group ID: corporateGroupGUID
3. Load the corporateGroup object.
4. Create a new term set and store it in the corporateTermSet variable. Use the following information:
o Method: corporateGroup.createTermSet
o Term set name: Contoso
o Term set ID: corporateTermSetGUID
o Location ID: 1033
5. Load the corporateTermSet object.
7. In the anonymous function for successes, set the text of the page element with ID status-message to
Group and term set created.
8. Call the createTerms function with no parameters.
9. In the anonymous function for failures, set the text of the page element with ID status-message to
Group and term set creation failed.
 Task 2: Create Terms in the New Term Set

1. Create a new function named createTerms.
2. In the new createTerms function, set the text of the page element with ID status-message to
Creating terms…
3. Create a new term and store it in a new variable named hrTerm. Use the following information:
o Method: corporateTermSet.createTerm()
o Name: Human Resources
o Location ID: 1033.
o Term ID: hrTermGUID
4. Load the hrTerm object.
5. Create a new term and store it in a new variable named salesTerm. Use the following information:
o Name: Sales
o Term ID: salesTermGUID

6. Load the salesTerm object.
7. Create a new term and store it in a new variable named technicalTerm. Use the following
information:
o Name: Technical

o Term ID: technicalTermGUID
8. Load the technicalTerm object.
9. Create a new sub-term in the technical term and store it in a new variable named engineeringTerm.
o Method: technicalTerm.createTerm()
o Name: Engineering
o Term ID: engineeringTermGUID
10. Load the engineeringTerm object.
11. Create a new sub-term in the technical term and store it in a new variable named softwareTerm. Use
the following information:
o Name: Software
o Term ID: softwareTermGUID
12. Load the softwareTerm object.
13. Create a new sub-term in the technical term and store it in a new variable named supportTerm. Use
o Name: Support
o Term ID: supportTermGUID

14. Load the supportTerm object.
Terms created.
17. Call the checkGroups() function to update the display of groups.
Error: Could not create the terms.
 Task 3: Test the Corporate Structure App

1. Start the app in debugging mode and authenticate with the following credentials:
o Password: Pa$$w0rd.
2. Trust the app and authenticate with the same credentials.

3. Examine the term sets that already exist and then create the corporate term set.
4. Stop debugging and close Visual Studio.
5. In Central Administration, open the Managed Metadata Service Application.
6. Explore the groups, term sets and terms in the Managed Metadata Service Application.
7. When you are satisfied that the app has created the terms correctly, close Internet Explorer.
Results: A SharePoint hosted app that can create a new group and a new empty term set in a term store.
Lab Discussion Questions

Discuss the following questions with the students:
 Why is it necessary to add a <script> tag to the

default.aspx page in Exercise 1, Task 3?
 Why is it necessary to add a permission request

for the Web scope to AppManifest.xml?
Lesson 3
Working with Managed Metadata Fields
In order to use the terms and keywords in a term set to tag documents, items, and assets, users must have
managed metadata fields. A managed metadata field is a type of site column that you can use in lists,
libraries, or content types. Other field types include Choice, Single Line of Text, and Lookup fields.
Managed metadata fields can be single-valued, in which case a user can tag an item with only one term.
Alternatively, if the metadata field is multi-valued, the user can tag an item with many terms from
multiple term sets. In this lesson you will see how to create managed metadata site columns, read terms
from fields, and add new tags to items in code.
Lesson Objectives
 Create managed metadata fields in SharePoint sites and connect those fields to specific term sets.
 Read and write values to single-valued managed metadata fields.
 Read and write values to multi-valued managed metadata fields.
Creating Managed Metadata Fields

To enable users to tag items in a SharePoint site
you must create a managed metadata site column
in the current site collection. This requires three
actions:
 Create the managed metadata field. A managed

metadata field is a site column with the type
TaxonomyFieldType.
 Create a hidden note field. In order to function

correctly, a managed metadata field requires a
hidden field of the Note type. This hidden note
field must be connected to the managed
metadata field by using a custom column.
 Connect the managed metadata field to a term set. If you connect the field to a specific term set, you
fix the term set from which the users can select tags. For example, in the "Product Categories" field,
users should be able to select terms from the "Products" term set but not from the "Social" term set.
Creating the Site Columns

The simplest way to create the managed metadata field and the hidden note field is to create CAML code
and pass it to the FieldCollection.AddFieldAsXml() method.
In the following JavaScript example, XML strings are created to the managed metadata and note fields
and passed to the AddFieldAsXML() method:
Creating Managed Metadata Fields in JavaScript

//Create XML for the hidden note columns
var xmlNoteField = '<Field ' +
'ID="{B758A862-9114-4B89-B73D-DFA806CB5101}" ' +
'Name="CorporateUnitTaxHTField0" ' +
'StaticName="CorporateUnitTaxHTField0" ' +
'DisplayName="Corporate Unit_0" ' +
'Type="Note" ' +
'ShowInViewForms="FALSE" ' +
'Required="FALSE" ' +
'Hidden="TRUE" ' +
'CanToggleHidden="TRUE" ' +
'RowOrdinal="0"></Field>';
//Create XML for the managed metadata field

//Use a custom column to connect the managed metadata field to the note field
var xmlMetaDataField = '<Field ' +
'ID="{ce641499-5955-4858-a4b5-9d994fdcea03}" ' +
'Name="CorporateUnit" ' +
'StaticName="CorporateUnit" ' +
'DisplayName="Corporate Unit" ' +
'Type="TaxonomyFieldType" ' +
'ShowField="Term1033" ' +
'EnforceUniqueValues="FALSE" ' +
'Group="Custom Columns"> ' +
' <Customization> ' +
' <ArrayOfProperty> ' +
' <Property> ' +
' <Name>TextField</Name> ' +
' <Value xmlns:q6="http://www.w3.org/2001/XMLSchema" ' +
' p4:type="q6:string" ' +
' xmlns:p4="http://www.w3.org/2001/XMLSchema-instance"> ' +
' {B758A862-9114-4B89-B73D-DFA806CB5101} ' +
' </Value> ' +
' </Property> ' +
' </ArrayOfProperty> ' +
' </Customization> ' +
'</Field>';
//Get the fields collection in the host web

var webFieldCollection = hostWeb.get_Fields();
context.load(webFieldCollection);
//Create and load the hidden note field

var noteField = webFieldCollection.AddFieldAsXml(xmlNoteField, true,
SP.AddFieldOptions.defaultValue);
context.load(noteField);
//Create and load the managed metadata field

var metaDataField = webFieldCollection.AddFieldAsXml(xmlMetaDataField(xmlMetaDataField,
true, SP.AddFieldOptions.defaultValue);
context.load(metaDataField);
//Execute the query

alert("Fields created.");
alert("Could not create fields.");
});
Connecting a Managed Metadata Field to a Term Set

By default, when you create a managed metadata site column, users can tag items with any term in the
managed metadata service application. To restrict users to tags from a particular term set, use the
TermSetId of the managed metadata field. To use this property, you must cast the field as a
TaxonomyField object. To perform this cast in JavaScript, which does not offer support for casting
classes, use the cast() method on the SharePoint ClientContext class.
The following JavaScript code illustrates how to connect a managed metadata column to a term set:
Connecting a Managed Metadata Field to a Term Set

var sspID = termStore.get_id();
var termSetGUID = "1438D56E-B131-C6B3-7653-369DAB3C10BD ";
//Get the metadata field as a taxonomy field

var metadataTaxonomyField = context.castTo(metaDataField, SP.Taxonomy.TaxonomyField);
context.load(metadataTaxonomyField);
//Execute the query

context.executeQueryAsync(function () {
//Make the connection to the term store and term set
metaDataTaxonomyField.set_sspId(sspID);
metaDataTaxonomyField.set_termSetId(termSetGUID);
metaDataTaxonomyField.update();
//Execute the query
alert("Connection made.");
}, function (sender, args) {
alert("Could not connect the taxonomy field to the field set.");
});
alert("Could load the taxonomy field");
});
Single-Value Fields
Taxonomy fields are site columns that can be used
to tag SharePoint items with terms from managed
metadata. When you create a taxonomy field, you
can specify whether the field is single-valued or
multi-valued. If the term is single-valued, the user
can add only one term to the item. This makes the
code for reading and setting tag values relatively
simple.
Reading Single-Valued Taxonomy Fields

Use the TaxonomyFieldValue class to read terms
from a managed metadata field. Cast the value of a
named field as the TaxonomyFieldValue class to
obtain the value. Once you have performed the cast, you can use the following properties to get
information about the tagged term:
 TermGuid. This property is the GUID of the term as stored in the term set.
 Label. This property is the default label of the selected term.
To access more information about the tagged term, such as full collection of labels, use the term GUID to
look the term up in the managed metadata term store.
The following code shows how to read the tagged term's GUID and default label from a list item's
managed metadata field. This example uses the .NET managed Client-Side Object Model (CSOM):
Reading a Managed Metadata Field Value

//Get the client context, the list, and the item
ClientContext context = new ClientContext("http://dev.contoso.com");
List productsList = context.Web.Lists.GetByTitle("Products");
context.Load(productsList);
ListItem product = productsList.GetItemById(1);

context.load(product);
//Get the value of the category field and cast it as a TaxonomyFieldValue

TaxonomyFieldValue categoryTaxValue =
(TaxonomyFieldValue)product.FieldValues["Category"];
context.load(categoryTaxValue);
//Now we can get information about the tagged term.

Console.WriteLine("The tagged term default label is: " + categoryTaxValue.Label);
Console.WriteLine("The tagged term GUID is: " + categoryTaxValue.TermGuid);
Setting Single-Valued Taxonomy Fields

To set the value of a managed metadata field, first get the field and cast it as a TaxonomyField. Then
create a new TaxonomyFieldValue object, set its properties, and pass it to the
TaxonomyField.SetFieldValueByValue() method:
Note: The TaxonomyFieldValue.TermGuid property must be set to the GUID of a term in

the term set. Look up this value in the term set to ensure it matches.
The following code shows how to set a tag for a single-valued taxonomy field:
Setting a Taxonomy Field

//Get the client context, the list, the field, and the item
List productsList = context.Web.Lists.GetByTitle("Products");
context.Load(productsList);
Field categoryField = productList.Fields.GetByInternalNameOrTitle("Category");

context.Load(categoryField);
ListItem product = productsList.GetItemById(1);

context.load(product);
//Cast the field as a taxonomy field

TaxonomyField categoryTaxField = (TaxonomyField)categoryField;
//Create a new Taxonomy Field Value and set its properties

TaxonomyFieldValue newTaxValue = new TaxonomyFieldValue();
newTaxValue.Label = "Bike";
newTaxValue.TermGuid = bikeTermGuid;
newTaxValue.WssId = -1;
//Set the taxonomy field

categoryTaxField.SetFieldValueByValue(product, newTaxValue);
//Update the item and execute the query

product.Update();
context.Load(product);
Multiple Value Fields

If the managed metadata field allows multiple
values, users can add as many tags as they like to
the field for each item. You can check whether the
field is multi-valued by using the
TaxonomyField.AllowMultipleValues property.
Reading Multi-Valued Taxonomy Fields

If a taxonomy field is multi-valued, then you can
cast the item field value as a
TaxonomyFieldValueCollection. Loop through the
items in this collection to read all the values.
The following code shows how to read tag labels

from a multi-valued managed metadata field. This example uses the .NET managed Client-Side Object
Model (CSOM):
Reading a Multi-Valued Managed Metadata Field

//Get the client context, the list, and the item
List tasksList = context.Web.Lists.GetByTitle("Tasks");
context.Load(tasksList);
ListItem firstTask = tasksList.GetItemById(1);

context.load(firstTask);
//Get the values of the skills field and cast them as a TaxonomyFieldValueCollection
TaxonomyFieldValueCollection skillsTaxValues =
(TaxonomyFieldValueCollection)firstTask["Skills"];
context.load(skillTaxValues);
//New we can loop through the values.

foreach(TaxonomyFieldValue currentValue in skillsTaxValues) {
Console.WriteLine("The tagged term default label is: " + currentValue.Label);
Setting Multi-Valued Taxonomy Fields

To set multiple values on a taxonomy field, create a new TaxonomyFieldValueCollection object and
pass it to the TaxonomyField.SetFieldValueByValueCollection() method. The constructor requires a
term value string that consists of the label and the GUID of the term.
The following example shows how to set two terms as tags in a multi-valued taxonomy field:
Setting Multi-Valued Taxonomy Fields

//GUIDs and labels of existing terms
string programmingSkillGUID = "ec786cda-1cd5-4380-9a06-67e6a7955868";
string programmingSkillLabel = "Programming";
string technicalWritingSkillGUID = "6aadea9f-a080-43df-91ed-b8cfdcf542a6";
string technicalWritingSkillLabel = "Technical Writing";
//Get the client context, the list, the field, and the item
List tasksList = context.Web.Lists.GetByTitle("Tasks");
context.Load(tasksList);
Field skillsField = tasksList.Fields.GetByInternalNameOrTitle("Skills");

context.Load(skillsField);
ListItem firstTask = tasksList.GetItemById(1);

context.load(firstTask);
//Cast the field as a taxonomy field

TaxonomyField skillsTaxField = (TaxonomyField)skillsField;
//Check that this is a multi-valued taxonomy field

if (skillsTaxField.AllowMultipleValues) {
//Prepare a string for the programming skill tag

string programmingSkillString = "-1;#" + programmingSkillLabel + "|" +
programmingSkillGUID + ";#";
//Prepare a string for the technical writing skill tag
string technicalWritingSkillString = "-1;#" + technicalWritingSkillLabel + "|" +
technicalWritingSkillGUID + ";#";
//Create the collection of taxonomy field values

TaxonomyFieldValueCollection tags = new TaxonomyFieldValueCollection(context,
programmingSkillString + technicalWritingSkillString, skillsTaxField);
//Set the field values

skillsTaxField.SetFieldValueByValueCollection(firstTask, tags);
//Update the item and execute the query

firstTask.Update();
context.Load(firstTask);
}
Lab B: Developing Managed Metadata Solutions (Part 2)

Scenario
You have a SharePoint hosted app that displays information from the Managed Metadata service
application and also creates a new taxonomy group and term set with terms that describe the Contoso
corporate structure. In order to apply these terms to items in lists and libraries, users require a managed
metadata site column that is bound to the Contoso term set. You have been asked to add code to the
Corporate Structure App that creates and connects such a managed metadata site column.
Objectives
 Obtain the host web of a SharePoint app web.
 Add metadata site columns to a SharePoint web site.
 Connect a metadata site column to a specific term set.
Lab Setup
The app includes no facilities for removing the managed metadata columns it creates. If, in Exercise 2, you
push the “Create Corporate Site Columns” button more than once, an error will be displayed because
columns already exist. If you want to remove columns so that you can execute the code again, run the
following PowerShell script: E:\Labfiles\Scripts\CleanUpMetaDataColumns.ps1
Exercise 1: Obtaining the Host Web

Scenario
The app must create site columns in the host web, not the app web. In this exercise, you will obtain a
reference to the host web by using a web info object.
1. Obtain a Web Info Object for the Host Web
2. Obtain the Host Web
 Task 1: Obtain a Web Info Object for the Host Web

1. Open the following solution in Visual Studio:
E:\Labfiles\Starter\CorporateStructureApp\CorporateStructureApp.sln.
2. In the App.js code file, in the createColumns function, write code that sets the text of the page
element with ID status-message to Obtaining the host web…
3. Use the context.get_web().get_parentWeb() method to get a web info object for the host web and
store it in a new variable named hostwebinfo.
4. Load the hostwebinfo object.
 Task 2: Obtain the Host Web

1. In the anonymous function for successes, get the host web and store it in the hostweb variable. Use
o Function: context.get_site().openWebById()
o Web ID: hostwebinfo.get_id()
2. Load the hostweb object.

Parent web loaded.
5. Call the addColumns() method.
Error: Could not load parent web.
Results: A SharePoint app that has a reference to the host web in preparation for creating site columns in
the host web.
Exercise 2: Adding Metadata Site Columns

Scenario
Now that you have accessed the host web, you will create site columns in the host web to support
metadata selection.

1. Add Metadata Site Columns to the Host Web
2. Connect a Metadata Site Column to a Term Set
3. Test the Corporate Structure App
 Task 1: Add Metadata Site Columns to the Host Web

1. Create a new function named addColumns.
2. In the addColumns function, write code that sets the text of the page element with ID status-
message to Creating site columns…
3. Get all the fields from the hostweb object and store them in a new variable named
webFieldCollection.
4. Create a new note field and store it in a new variable named noteField. Use the following
information:
o Method: webFieldCollection.addFieldAsXml()
o Field XML: xmlNoteField

o Add to default view: true
o Add field options: SP.AddFieldOptions.defaultValue
5. Load the noteField object.
6. Create a new metadata field and store it in a new variable named metaDataField. Use the Following
information:
o Method: webFieldCollection.addFieldAsXml()
o Field XML: xmlMetaDataField
o Add to default view: true
o Add field options: SP.AddFieldOptions.defaultValue
7. Load the metaDataField object.
Columns added.
10. Call the connectFieldToTermSet function.

Error: Could not create the columns.
 Task 2: Connect a Metadata Site Column to a Term Set

1. Create a new function named connectFieldToTermSet.
2. In the connectFieldToTermSet function, set the text of the page element with ID status-message to
Connecting the columns to the term set.
3. Get the ID of the termStore and store it in a new variable named sspID.
4. Cast the metaDataField object as a SP.Taxonomy.TaxonomyField and store it in a new variable

named metaDataTaxonomyField.
5. Load the metaDataTaxonomyField object.
7. In the anonymous function for successes, set the sspId of the metaDataTaxonomyField object to
sspID.
8. Set the termSetId of the metaDataTaxonomyField object to corporateTermSetGUID.
9. Call the update() method on the metaDataTaxonomyField object.

Connection made. Operations complete.
Error: Could not connect the taxonomy field.


1. Start Internet Explorer, browse to the http://dev.contoso.com SharePoint site and authenticate with
the following credentials:
2. Browse to the list of Site columns in the web site and note the columns in the Custom Columns
category.
3. In Visual Studio, start the app without debugging and trust the app. Use the following credentials to
authenticate:
4. In the Corporate Structure App, create the corporate site columns.
5. In the Site Columns list for the http://dev.contoso.com site, note the new column in the Custom
Columns category.
6. Verify that the new site column is bound to the correct term set.
Results: A SharePoint-hosted app that can create site columns for metadata.

Discuss the following questions with the class:
 Why does the Corporate Structure app require

a permission request for the Web scope when it
deals with managed metadata?
 In order to use the Corporate Unit site column

with items in a list or library, what other steps
must a user or site administrator take?

Managed metadata is a versatile system that you can use to tag SharePoint items, documents, and assets
with a centrally managed set of descriptive terms. These terms can help to categorize and describe
content, which makes content easier to find and understand. Users can follow terms and terms can be
used to drive navigation in web publishing sites. By using the Microsoft.SharePoint.Taxonomy object
model and its client-side equivalents, you can write code that creates term sets and applies terms to items
in SharePoint lists.
Review Question(s)
Question: The marketing team has created the term "Sales Lead" in the Marketing term set.
The sales team wants to use the same term in the Sales term set. When sales personnel make
changes to the new term, you do not want those changes to apply to the term in the
Marketing term set. How can you satisfy this requirement?
Statement Answer
True or False: When you create a managed

metadata site column, you can control the term
set that users pick terms from.
3-1
Module 3
Interacting with the Search Service
Contents:
Module Overview 3-1
Lesson 1: Understanding the SharePoint 2013 Search Service 3-2
Lesson 2: Building Search Queries with KQL and FQL 3-13
Lesson 3: Executing Search Queries from Code 3-18
Lab: Executing Search Queries from SharePoint Apps 3-26
Module Overview
The goal of this module is to enable students to create and execute search queries from client-side and
server-side code. The module provides an overview of the search service architecture in Microsoft®
SharePoint® 2013 as it relates to developers, before describing how to construct queries by using
Keyword Query Language (KQL) and FAST Query Language (FQL) and how to submit these queries to the
search service.
Objectives
 Describe the SharePoint 2013 Search Architecture.

 Build simple and advanced KQL Queries.
 Describe the SharePoint Search Index.
 Describe and work with crawled and managed properties.

 Describe the levels and security of the SharePoint Search Schema.
3-2 Interacting with the Search Service
Lesson 1
Understanding the SharePoint 2013 Search Service
Explore the architecture of the search service from a development perspective.
Lesson Objectives
 Describe the SharePoint Search Architecture.
 Describe the structure of the search index.
 Describe what a crawled property is and how they are created.
 Describe what a managed property is and how they are created.
 Describe the various settings of a managed property.
 Modify the search schema at various levels.
Search Service Architecture

The Search service has been re-architected in
SharePoint 2013 to provide enhanced operation
and a higher level of search component
redundancy. This improves performance, resilience,
and availability of the search service. As an
increasing number of both internal and Internet-
facing sites provide search-driven navigation, search
has become more than just a useful tool; it is the
core of many business websites. SharePoint 2013
Enterprise Search has most obviously changed with
the integration of the functionality previously
provided by deploying FAST for SharePoint 2010.
For end users, this provides integral context-sensitive item preview for documents and other result set
items.
Following its radical rebuild, the Search architecture is now made up of the following components:
 Crawl
 Content Processing
 Analytics Processing
 Indexing
 Query Processing
 Search Administration
There are two core functions of search: content ingestion and content query. Without effective content
ingestion, contributor content will not be effectively indexed. For search users, it is essential to have
indexed content available quickly and to ensure that search queries surface the most relevant content in
their result sets.
Content ingestion
The process flow for ingesting content into the search index uses the following components:
 Crawl. The crawl component can search content across a range of content sources—from both
Microsoft platforms and third-party sources. Access to these is provisioned by connectors. There are a
number of connectors shipped with SharePoint 2013. Crawled content is held in the crawl database.
 Content Processing. The crawl component passes the crawled content to the content processing
component. This component performs tasks such as parsing documents, property mapping, and
processing linguistics, all of which create artifacts that can be stored in the search index. In addition,
this component processes URL links, which are stored in the link database.
 Analytics Processing. The analytics processing component analyzes the crawled items and how users
interact with search results.
 Index. The index component writes artifacts to the index file, which is actually a number of files and
folders. This component also manages the index partitions and replicas, ensuring that indexed
content is valid.
You can deploy multiple instances of these components to scale out your search architecture.
Content Query
The process for servicing user search queries is as follows:
1. A client interface, such as the Search Center, passes a query through a web front-end (WFE) to the
query processing component.
2. The query processing component performs some linguistic processing to maximize query efficiency
and effectiveness, such as word stemming and initiation of query rules. The processed query is then
passed to the index component.
3. The index component interrogates the search index and returns a result set to the query processing
component. This component processes these results to remove duplicates and performs any
additional security trimming that is required, and then passes the result set to the WFE to be rendered
to the client application.
Search Administration
The Search Administration Component runs system processes required for search. It is responsible for
search provisioning and managing topology changes, and it coordinates interaction between the other
search components—Content Processing, Query Processing, Analytics Processing, and Index Component.
Search Processes and Data Flow

The SharePoint Search architecture is made up of
six roles:
 Administration. Administration is responsible

for storing and making changes to the search
topology. This service must be running in order
to modify the topology and to see information
about the topology in Central Administration.
 Crawling. Crawling is responsible for gathering

the content from the various content sources.
 Content Processing. Content Processing is
responsible for processing the crawl and
managed properties by executing various steps (also known as flows).
 Analytics Processing. Analytics Processing handles the storage and processing of all analytics data
related to search items.
 Query Processing. The query processing component handles all queries to the index. It performs
various linguistic processing procedures before sending the query to the index.
 Index. The index component stores and manages the indexed search data.
Any and all of these roles can be played by any server in the SharePoint Farm. A welcome change in the
search architecture is the ability to have more than one administration component for redundancy.
Search Host Controller

Each of these components is managed by HostControllerService.exe. When started, this Windows service is
responsible for starting all the components on the respective server. When a particular process needs to
be enabled on a server in the farm, a NodeRunner.exe process is started with the specific role as its
configuration. The exception to this is the Crawling component, which is still run in the older search
service process mssmdm.exe.
The following code example shows how to create a Search Service Application instance by using Windows
PowerShell:
Creating a Search Service Application by Using Windows PowerShell

$serverName = "LONDON"
$mgAcct = Get-SPManagedAccount Contoso\SPServices

$appPool = New-SPServiceApplicationPool –Name SearchAppPool –Account $mgAcct
$appPool = Get-SPServiceApplicationPool SearchAppPool
$searchApp = New-SPEnterpriseSearchServiceApplication –Name "Contoso Search" –

ApplicationPool $appPool –DatabaseName "Contoso_Search_DB"
$searchAppProxy = New-SPEnterpriseSearchServiceApplicationProxy –Name "Contoso Search" –
SearchApplication $searchApp
Start-SPEnterpriseSearchQueryAndSiteSettingsServiceInstance $serverName
Start-Sleep -m 60000
$instance = Get-SPEnterpriseSearchServiceInstance $servername

Start-SPEnterpriseSearchServiceInstance $instance
#wait for the service to start - 60 secs

Start-Sleep -m 60000
Set-SPEnterpriseSearchAdministrationComponent –SearchApplication $searchApp –

searchServiceInstance $instance
$active = Get-SPEnterpriseSearchTopology –SearchApplication $searchApp –Active

Get-SPEnterpriseSearchComponent –SearchTopology $active
$clone = New-SPEnterpriseSearchTopology –SearchApplication $searchApp –Clone –

SearchTopology $active
New-SPEnterpriseSearchContentProcessingComponent –SearchTopology $clone –

SearchServiceInstance $instance
New-SPEnterpriseSearchIndexComponent –SearchTopology $clone -SearchServiceInstance

$instance -IndexPartition 0
New-SPEnterpriseSearchAnalyticsProcessingComponent -SearchTopology $clone -

New-SPEnterpriseSearchQueryProcessingComponent -SearchTopology $clone -

New-SPEnterpriseSearchCrawlComponent -SearchTopology $clone -SearchServiceInstance

$instance
New-SPEnterpriseSearchAdminComponent –SearchTopology $clone –searchServiceInstance

$instance
Set-SPEnterpriseSearchTopology –Identity $clone
How Search Works
Once you have set up a search service application, it is important to know the series of steps that occur
when the content is processed. This will help you to better debug issues with your search results. The
high-level steps include:
1. The Search Crawler will connect to the target source and retrieve the crawl properties, security
information, and file contents.
2. SharePoint will add the item URL to the crawl database.

3. Item data will be passed to the content processing component.
4. Content Processing component will pass the item data through more than 70 flows, each flow having
a specific role in the content processing pipeline. For example, major flows include document parsing
and format handling, adding and retrieving data from the Analytics Component and Database, and
the Content Enrichment service web service callout.
5. Once all of the proper flows have been executed, the transformed metadata is passed to the indexing
component.
6. The Indexing component will determine the type of operation that should be applied, and then
perform the operation on the file based index.
7. Once added to the index, the search query component will take user- and application-submitted
queries and transform them before sending to the index component for retrieval.
8. The Indexing component will find all matching items and then pass the results back to the Query
component.
9. The Query component will do any required sorting and relevance operations.
Demonstration: Exploring the Search Architecture

This demonstration shows you the default search architecture in SharePoint 2013.
Demonstration Steps
3. Open SharePoint Central Administration

4. Browse to the management page for the Contoso Search service application.
5. Review the Search Administration page. Notice the Search Application Topology section and how
each role is assigned to a single server. Also notice how you cannot change the topology by using the
administration web site in SharePoint 2013, this must be done by using Windows PowerShell.
6. Open Task Manager
7. On the Details tab, review the processes that are running as noderunner.exe.
8. Open the Services applet.
9. Browse to the SharePoint Search Host Controller service
10. Right-click the service, select Stop
11. Switch back to SharePoint Central Administration, press F5 to refresh the page.
12. The page will fail to load because the administration service is down.
13. Switch to the Services applet
14. Notice how all the noderunner.exe processes have been removed
15. Start the SharePoint Search Host Controller

16. Switch to SharePoint Central Administration. Refresh the page, and you should see the services
slowly come back up.
17. Switch to Task Manager, you should now see the noderunner.exe processes have started again.
The Search Index

After setting up your architecture and Search
Content Sources, you will execute crawls to index
the content in those sources. Using both the out-of-
box connectors and connector customization APIs,
this content can be from anywhere on your
network. As part of the process, the crawler will
gather the content and any properties about that
content by using a protocol handler. Once the
properties have been gathered, they are then
processed and placed into the index.
The SharePoint Search index is a file system-based

index. By default, it is stored in the C:\Program
Files\Microsoft Office Servers\15.0\Data\Office
Server\Applications\Search\Nodes\<NODEID>\IndexComponent<ID>\storage\data directory. It is made
up of several subdirectories that partition the index into update groups. Each time an item changes, it
must be re-crawled and updated in the index. To reduce the indexing load, SharePoint 2013 introduced
these separate index update groups:
 Default. The default index update group contains all managed properties that do not belong to the
Security, Link, Usage, or People index update groups.
 Security. The security index update group contains the document Access Control List (ACL) managed
property.
 Link. The link index update group contains the managed properties related to link structure.
 Usage. The usage index update group contains the managed properties related to usage data.
 People. The people index update group contains the managed properties related to people search.
The index can be made redundant by adding more index roles to the farm. These roles can then provide
index redundancy by becoming a replica or a partition of the index. This mimics the architecture
functionality of FAST Search’s rows and columns. In order to add new replicas or partitions, you must use
Windows PowerShell and have more than one search server in your farm.
The following code examples shows you how to add a new index partition to SharePoint Search by using
Windows PowerShell:
Using Windows PowerShell to Add a New Index Partition

$newssi = Get-SPEnterpriseSearchServiceInstance -Identity "svr-spapp02"
$ssa = Get-SPEnterpriseSearchServiceApplication
$activeTopology=Get-SPEnterpriseSearchTopology -Active -SearchApplication $ssa
$newTopology = New-SPEnterpriseSearchTopology -SearchTopology $activeTopology -
SearchApplication $ssa –Clone
New-SPEnterpriseSearchIndexComponent -SearchTopology $newTopology -SearchServiceInstance

$newssi -IndexPartition 1
Set-SPEnterpriseSearchTopology -Identity $newTopology
Crawled Properties
As previously mentioned, the crawler is responsible
for finding properties about the crawled content.
This includes the content binary and any other
protocol and source specific metadata. In some
cases the number of crawled properties remains
constant; in other cases (like a SharePoint List), you
may find that new columns have been added. In the
case of the list, the new properties are discovered
automatically and show up in the search schema
after a successful crawl.
Crawl properties are groups into categories. These

categories are normally mapped to the iFilter or
protocol handler that found them, but can also be used as a way of finding the specific property you are
looking for.
The following code example shows you how to retrieve all crawled properties by using Windows
PowerShell:
Getting All Crawled Properties by Using Windows PowerShell

$searchApp = Get-SPEnterpriseSearchServiceApplication
Get-SPEnterpriseSearchMetadataCrawledProperty –SearchApplication $searchApp | sort

categoryname, name | group –property categoryname
Creating Crawled Properties

The SharePoint Search crawler will automatically add new crawled properties as they are discovered.
When creating a crawl property manually by using Windows PowerShell, you must call the New-
SPEnterpriseSearchMetadataCrawledProperty cmdlet. This cmdlet requires the following parameters:
 Search Application. The search application in which to create the crawled property.
 VariantType. The type of the crawled property.
 Category. The category in which the property should be placed.
 Name. The name of the crawled property.

Additional Reading: For more information on the

SPEnterpriseSearchMetadataCrawledProperty cmdlet, see New-
SPEnterpriseSearchMetadataCrawledProperty at http://go.microsoft.com/fwlink/?LinkId=321929.
The following code example shows how to create a new crawled property by using Windows PowerShell:
Creating a New Crawled Property

$searchapp = Get-SPEnterpriseSearchServiceApplication $searchApplicationName
$category = Get-SPEnterpriseSearchMetadataCategory –Identity SharePoint -

SearchApplication $searchapp
New-SPEnterpriseSearchMetadataCrawledProperty -SearchApplication $searchapp -VariantType

1 -Category $category -PropSet "00130329-0000-0130-c000-000000131346" -Name "My Crawled
Property" -IsNameEnum $false
Managed Properties
Managed properties are mappings to crawl
properties that can be used in various different
ways in Search. Managed properties have several
settings that determine how the contents will be
displayed in search results. These settings include:
 Type. This is the data type of the managed

property. This can be Text, Integer, Decimal,
Date and Time, Yes/No, Double precision float,
and binary. This attribute also will determine
what types of operators you can use in queries.
 Searchable. This will add the managed property

to the full-text index and allow you to run
queries against the managed property without explicitly specifying the property name.
 Queryable. Allows you to query the managed property by explicitly using the property name.
 Retrievable. Will allow you to display this property in the search results.
 Allow Multiple Values. Allows the property to store more than one value. This is helpful for managed
properties like Author.
 Refinable. When set to “yes”, the managed property can be used to drill down into search results by
using the refinement web part.
 Sortable. When set to “yes”, you can use the managed property to sort results.
 Safe for Anonymous. Allows the property to be visible for anonymous users; typically used on
Internet-facing sites.
 Alias. Can be used to change the name to something more meaningful. Used when you don’t have
permissions to create new managed properties.
 Token Normalization. When enabled, results are returned ignoring casing and diacritics.
 Complete Matching. Forces an exact match search on managed properties. Any substring search will
not be returned.
 Custom Entity Extraction. Tells the system that the managed property should be processed as part of
the respective entity extraction dictionary. This is explored in a later module.
Mapping Crawled Properties

Crawled properties must be mapped to a managed property in order to be searchable. There is a very
specific ordering of the mapped crawled properties. For single-valued managed properties, the first
crawled property to have a value is the one that is used. All others will be ignored. In order to get all of
the values, you must set the property to have multiple values.
When adding columns to lists, they automatically are added as crawl and managed properties. The crawl
property naming convention is:
 ows_q_<Type>_<ColumnName>
 ows_r_<Type>_<ColumnName>
 ows_taxId_<Type>_<ColumnName>
Managed property naming convention is:
 <ColumnName>OWS<Type>
 owstaxId<ColumnName>
All spaces are removed in the names of the properties.
Creating Managed Properties

You can create managed properties through the user interface or by using Windows PowerShell. When
using the UI, you can create them at the Service Application, Tenant, and Site Collection levels. You
cannot create them at the site level. When using the Windows PowerShell New-
SPEnterpriseSearchMetadataManagedProperty cmdlet, the default scope is the service application.
You can use the SiteCollection and Tenant parameters to specify the scope.
Additional Reading: For more information on how to create managed properties by using
Windows PowerShell, see New-SPEnterpriseSearchMetadataManagedProperty at
http://go.microsoft.com/fwlink/?LinkId=321930.
The following code example shows how to create managed properties by using Windows PowerShell:
Creating Managed Properties by Using Windows PowerShell
$managedproperty = New-SPEnterpriseSearchMetadataManagedProperty -SearchApplication

$searchapp -Name "My Managed Property" -Type 1
$crawledproperty = Get-SPEnterpriseSearchMetadataCrawledProperty -Name "My Crawled

Property" -SearchApplication $searchapp
New-SPEnterpriseSearchMetadataMapping -SearchApplication $searchapp -ManagedProperty

$managedproperty -CrawledProperty $crawledproperty
Demonstration: Exploring Crawl and Managed Properties

In this demonstration, you will view the default crawled and managed properties.
Demonstration Steps
3. Open SharePoint Central Administration.
4. Under Application Management, click Manage service applications.
5. Click Contoso Search.
6. In the quick launch, under Queries and Results, click Search Schema.
7. The default view will show managed properties.
8. Do a search for author.
9. Click the Author managed property.
10. Review each of the settings for the managed property.

11. Specifically notice the crawled property mappings and how there are several mapped to this single
managed property.
12. Click OK.
13. In the navigation at the top of the page, click the Crawled Properties link.
14. In the Category drop-drown list, select People.
15. Do a search for name.

16. Click the People:AccountName crawled property.
17. Check the Include in full-text index checkbox.
18. Click OK.

19. In the navigation at the top of the page, click the Categories link.
20. You should be presented with a list of crawled property categories and how many exist in each
category.

Search Schema
The entire set of crawl and managed properties
make up part of the search schema. The entire set
includes:
 Crawl Properties
 Managed Properties
 Mappings
 Query Rules
 Aliases
 Result Sources
 Result Types
Once you have created a search service application, you will have a basic set of known crawled and
managed properties. As you continue to index content sources, new crawled and managed properties will
be added.
Search Schema Levels

You also have the option to add your own crawl and managed properties. In SharePoint 2010, you were
only allowed to do this at the search service application level. In SharePoint 2013, you can have a multi-
leveled search schema. These levels include:
 Service Application
 Site Collection
 Site
Each level can see the managed properties and other values at the same level or higher.
Demonstration: Exploring the Search Schema

This demonstration provides you with an overview of the search schema in SharePoint 2013.
Demonstration Steps

3. Open a browser to the Search Center (http://search.contoso.com).
4. Click the site settings icon, then click Site Settings.
5. Under the Search section, click Schema. You should see that you have no ability to create a managed
property at this level.
6. In the browser, click Back.
7. Under the Search section, click Result Sources.
8. Click New Result Source.
9. For the name, type Tasks (Site)
10. Click Save

12. Under Site Collection Administration, click Search Schema.
13. Click New Managed Property
14. For the property name textbox, type Classification.
15. Notice how you can only add Text and Yes/No property types. You cannot specific multiple values,
and you cannot add it as a refiner or as sortable.
16. Click OK.
18. Under Site Collection Administration, click Search Result Sources. Notice that the Tasks (Site)
result type you just created is not visible.
20. For the name, type Tasks (SiteCol).
21. Click Save.
22. Click the site settings icon, and then click Site Settings.
23. Under Site Collection Administration, click Schema.
24. For a search for Classification, you should see the site collection property you created.
25. Click the site settings icon, and then click Site Settings.
26. Click Result Sources. You should see the site collection result source.
27. In a new browser tab, open SharePoint Central Administration.
28. Click Manage service applications.

30. Click Result Sources. You should not see the site collection or site level result sources created
previously, as they are out of scope.
Lesson 2
Building Search Queries with KQL and FQL
In this lesson you will learn about the two different queries languages that SharePoint supports. You will
also learn how to build both simple and advanced queries to search for specific content.
Lesson Objectives
 Describe the two supported search query languages.
 Describe Keyword Query Language (KQL) syntax.
 Describe how to use KQL Operators.
 Create simple and advanced queries.
 Enable and execute Fast Query Language (FQL) queries.
SharePoint Query Languages

Every search engine has a query language that
enables users and applications to find the
information in the index. Some query languages are
simpler than others, based on the features of the
search engine itself. Because SharePoint Search has
evolved from two bases (SharePoint Search and
FAST Search), there are two different query
languages that are supported. These two query
languages are:
 Keyword Query Language (KQL)
 FAST Query Language (FQL)
KQL is the default and recommended query language, and will be used when users and applications
submit queries to the search engine. In order to use FQL, you must enable it manually.
SQL Syntax queries, also known as FullTextSqlQuery, are no longer supported. Any older applications that
utilize this language will break when moving to SharePoint 2013.
Keyword Query Language (KQL) Queries

KQL is the default query language for building
SharePoint search queries. Using KQL, you specify
the search terms or property restrictions that are
passed to the SharePoint search service.
KQL is what users will use to submit queries to the

query engine. It is important that end users are
educated on how to properly submit these queries.
If they can’t be educated quickly, then it is a good
idea to provide examples or applications that will
assist them in finding what they are looking for.
KQL queries are made up of free-text keywords,

managed property restrictions, and optional
operators. Keyword KQL queries are not case sensitive, but the operators are, as you will learn more about
in the next topic. By default, the maximum length is 2,048 characters, but by using coding you can extend
the length up to 20,480 characters. Simple words and phrases are supported. Phrases are supported by
using double quotes to designate them. When you construct your KQL query by using free-text
expressions, search in SharePoint 2013 matches results for the terms you chose for the query based on
terms stored in the full-text index. This includes managed property values where FullTextQueriable is set
to true.
Some examples of simple KQL queries include:
 SharePoint
 Aaren Ekelund
 Author:"Adam Barr"
As you are about to learn, queries can get much more complex when adding operators.
KQL Operators
Simple KQL queries can get most users what they
are looking for, but there are many more use cases
where you need to apply operators to find very
specific information. To construct complex queries,
you can combine multiple free-text expressions
with KQL query operators. If there are multiple free-
text expressions without any operators between
them, the query behaviour is the same as using the
AND operator.
The available KQL operators are:
 Wildcard (*). Enables you to do prefix matching.

Suffix matching is not supported in SharePoint
2013.
 Colon (:). Contains operator for managed properties.
 Equals (=). Compare operator.
 Less than (<). Basic comparison operator.

 Greater than (>). Basic comparison operator.
 Less than equal too (<=). Basic comparison operator.
 Greater than equal too (>=). Basic comparison operator.
 Not equal too (<>). Basic comparison operator.
 AND. Returns search results that include all of the free text expressions, or property restrictions
specified with the AND operator. This is the same as the “+” operator.
 NOT. Returns search results that do not include the specified free text expressions or property
restrictions. This is the same as the “-“ operator.
 OR. Returns search results that include one or more of the specified free text expressions or property
restrictions.
 NEAR. The NEAR operator matches the results where the specified search terms are within close
proximity to one another, without preserving the order of the terms.
 ONEAR. The ONEAR operator matches the results where the specified search terms are within close
proximity to each other, while preserving the order of the terms.
 XRANK. The XRANK operator boosts the dynamic rank of items based on certain term occurrences
within the match expression, without changing which items match the query.
 WORDS. The WORDS operator specifies that the terms in the query are synonyms, and that results
returned should match either of the specified terms. You can use the WORDS operator with free text
expressions only; it is not supported with property restrictions in KQL queries.
Advanced KQL
You can build very advanced search queries by
using the KQL operators. Here are some examples
of advanced queries:
 Find all word documents modified after a

certain date: Write>1/1/2013 FileType:docx
 Find all items that have Microsoft and
SharePoint in the index: “Microsoft” AND
“SharePoint”
 Find all items that have either Microsoft or
SharePoint in the index: “Microsoft” OR
“SharePoint”
 Find all items that have the complete phrase “Microsoft SharePoint”: “Microsoft SharePoint”
 Do a People search for first of Dan and title of CEO: FirstName:Dan JobTitle:CEO
 Find all items of type Task in the team web application: Path:http://team.contoso.com
ContentType:Tasks
 Search for documents that have the words “SharePoint” and “Microsoft” within two words of each
other: "SharePoint" NEAR(n=2) "Microsoft"
 Find all People that have a last name that starts with “Sm”: LastName:Sm*
 Do a search ranking all items with “IE” or “Internet Explorer” in them equally: WORDS (IE, Internet
Explorer)
Note: You should be careful with the filenames in files that you index. The default word
breaking engine in SharePoint will only break the words apart if they have underscores (“_”) or
dashes (“-“). If you search for a name of a document that has no word breakers, you will not find
them based on the filename unless you use a wildcard prefix.
FAST Query Language (FQL) Queries

FQL is a structured query language that supports
advanced query operators for developers. You can
use FQL when you want to create complex queries
that you want to pass programmatically to the
SharePoint search service. FQL isn’t intended to be
exposed to end users, and is disabled by default.
Like KQL queries, FWL queries are limited to 2,048

characters and are not case-sensitive. FQL also has
the following reserve words:
and, or, any, and, not, count, decimal, rank, near,
onear, int, in32, int64, float, double, datetime, max,
min, range, phrase, scope, filter, not, string, starts-
with, ends-with, equals, words, xrank
FQL queries have three main elements:
 Token expressions. These are terms, phrases or numeric values.
 Property specification. These are the managed properties or full-text index you are querying upon.
 Operators. These are similar to the KQL operators.
Operators are similar to KQL, but include a couple that KQL does not have. Operators include:
 AND. Returns only items that match all expressions.
 ANDNOT. Returns items that match first operand and do not match the second.
 ANY. Similar to OR, but number of operands and distance between do not matter.
 COUNT. The number of query terms an item must have to be included in results.
 DATETIME. Used for explicit type conversion. In most cases this is not needed when the target
managed property is of the proper type.
 DECIMAL. Used for explicit typing of numeric values.
 ENDS-WITH. The given expression must be at the end of the managed property.
 EQUALS. Must have an exact token match with expression.

 FLOAT. Used for explicit typing of numeric values.
 INT. Used for explicit typing of numeric values.
 NEAR. Used to find items that are N terms away from each other.
 NOT. Returns items that don’t match the expression.
 ONEAR. The ordered variant of NEAR.
 OR. Used to find items with multiple expressions. Items that match more of the OR operands are
higher in the rankings.
 PHRASE. Used to match an exact string of tokens.
 STARTS-WITH. A managed property value must start with the given expression.
 STRING. Used for Boolean matching of a text string.
 XRANK. A dynamic ranking boost operand.
Note: Note that FQL allows both prefix and suffix wildcard searches, and KQL only allows
prefix searches.
Additional Reading: For more information on FAST Query Language, see FAST Query
Language (FQL) syntax reference at http://go.microsoft.com/fwlink/?LinkId=321932.
Enabling FQL
To enable FQL in your applications, you must set the EnableFQL property on the search query. This can be
done programmatically and in REST service calls.
Changed in FQL
FQL isn’t exactly the same FQL from SharePoint 2010. Here are some changes you should be aware of:
 ANY operator is the same as the OR operator, but can also be replaced with the WORDS operator.
 RANK operator is valid, but not used in the ranking operations.

 XRANK syntax has been modified; older XRANK queries will not work.
 STRING operator ignores the N parameter.
 STRING operators does not support ANNOTATION_CLASS.
 Numeric data types must be declared explicitly.
FQL Query Examples

Below are some examples of how to use FQL queries.
 Find any items that contain Microsoft or SharePoint with no relevance manipulation: any(Microsoft,
SharePoint)
 Find any items that contain Microsoft or SharePoint with relevance manipulation: or(Microsoft,
SharePoint)
 Find items that contain between five and 10 instances of SharePoint: count(SharePoint, from=5,
to=10)
 Find items that have Microsoft, but do not have SharePoint: andnot(Microsoft, SharePoint)
 Find items that have both Microsoft and SharePoint: and(Microsoft, SharePoint)
 Find any documents with Author that starts with Dan: author:starts-with(“Dan”)
Lesson 3
Executing Search Queries from Code
In this lesson you will learn the various ways to execute queries against the SharePoint search index.
Lesson Objectives
 Describe the various Search APIs.
 Build search applications that use the Search Web Service.
 Build search applications that use server side code.
 Build search applications that use client side code.
 Build search applications that use REST API.
Search APIs
There are several ways to submit a query to
SharePoint Search, these include:
 User Interface (UI)

 Web Services
 Server Object Model
 Client Side Object Model
 REST
No matter which API you choose, all queries are

processed by the same query and indexing
components against the same index. Because of the
rich number of standards-based APIs, you can easily build search applications in any number of languages
and frameworks. This enables you to integrate your internal applications with SharePoint search to
enhance user usability. From a non-programmatic standpoint, the user interface is the easiest way to
submit queries to SharePoint.
User Interface
You can perform a search from any site in the SharePoint farm by using the search textbox. If you have set
up a global search center URL, all queries will go to the same URL to be processed. In most cases the
query text is pulled from the query string, as shown in the following example:
http://search.contoso.com/sites/Search/Pages/results.aspx?k=sharepoint
Executing Web Service Queries

The Web Services API has been around for the past
few versions of SharePoint and exists in SharePoint
2013, but has become a deprecated API. This means
that you can still use it, but it may not work in
future versions. You can access the search web
service by appending the “/_vti_bin/spsearch.asmx”
suffix to the end of any site URL, as shown in this
example:
http://teams.contoso.com/_vti_bin/spsearch.asmx
The service has four main methods:
 Query
 QueryEx
 Registration
 Status
Both the Query and QueryEx methods accept an XML string that contains a specially formatted query
request.
The QueryEx method returns the search results in a System.Data.DataSet object. The DataSet object
contains a System.DataSet.DataTable object for each result type that is returned.
The Query method returns the search results in a string as XML. The format for the XML is defined by the
Microsoft.Search.Response and Microsoft.Search.Response.Document schemas. The full set of search
results is contained in the Results element of the Microsoft.Search.Response schema, with each
individual result represented by a Document element of the Microsoft.Search.Response.Document
schema.
The following code example shows how to call the SharePoint Web Service endpoint:
Code to Call the SharePoint Web Service End Point

SPSearchWS.QueryService svc = new SPSearchWS.QueryService();
svc.Url = "http://search.contoso.com/_vti_bin/search.asmx";
svc.UseDefaultCredentials = true;
var query = String.Format(

@"<QueryPacket>
<Query>
<Context>
<QueryText type='STRING' language='en-us' >""{0}""</QueryText>
<LanguagePreference>en-us</LanguagePreference>
</Context>
<Properties>
<Property name='path'/>
<Property name='title'/>
</Properties>
<EnableStemming>true</EnableStemming>
</Query>
</QueryPacket>", this.TextBox1.Text);
DataSet ds = svc.QueryEx(query);
this.GridView1.DataSource = ds;
this.GridView1.DataBind();
Executing Server-Side Queries

You can execute queries in server object model
applications that run on the SharePoint servers by
using the
Microsoft.Office.Server.Search.Query.KeywordQ
uery class that is contained in the
Microsoft.Office.Server.Search.dll assembly. This
method is simpler than a web service call as it
exposes all the possible configuration values as
properties of the class rather than them being
specially formatted in the XML request. The older
Execute method of the KeywordQuery is obsolete
and has been replaced by the SearchExecutor
class. This SearchExecutor class enables you to execute more than one query in a batch.
Additional Reading: For more information on the properties available in the

KeywordQuery class, see KeywordQuery class at http://go.microsoft.com/fwlink/?LinkId=321934.
Here is an example of how to use the KeywordQuery class and its Execute method to run a query:
Server-Side Code to Call SharePoint Search by Using KeywordQuery.Execute with FQL Query
SearchQueryAndSiteSettingsServiceProxy settingsProxy =
SPFarm.Local.ServiceProxies.GetValue<SearchQueryAndSiteSettingsServiceProxy>();
SearchServiceApplicationProxy searchProxy =
settingsProxy.ApplicationProxies.GetValue<SearchServiceApplicationProxy>("Contoso
Search");
KeywordQuery keywordQuery = new KeywordQuery(searchProxy);

keywordQuery.EnableFQL = true;
keywordQuery.QueryText = "author:ends-with(murphy)";
keywordQuery.ResultsProvider = SearchProvider.Default;
keywordQuery.ResultTypes = ResultType.RelevantResults;
ResultTableCollection resultsTableCollection = keywordQuery.Execute();
ResultTable searchResultsTable = resultsTableCollection[ResultType.RelevantResults];

DataTable resultsDataTable = new DataTable();
resultsDataTable.TableName = "Results";
resultsDataTable.Load(searchResultsTable, LoadOption.OverwriteChanges);
In some cases you will want to execute more than one query at a time. You can do this by migrating your
older code to the new SearchExecutor class.
The following code examples show how to utilize the SearchExecutor class to execute multiple queries:
Code to Run More Than One Query by Using the SearchExecutor Class
public static Dictionary<string,DataTable> ExecuteMultipleQueries()
{
DataTable tableResults = null;
Dictionary<string, DataTable> searchResults = new Dictionary<string, DataTable>();
using (SPSite site = new SPSite("http://team.contoso.com"))

{
Dictionary<string, Query> queries = new Dictionary<string, Query>();
Dictionary<string, ResultTableCollection> results;
using (KeywordQuery query1 = new KeywordQuery(site))

{
query1.QueryText = "title:\"SharePoint\"";
query1.RowLimit = 100;
SearchExecutor se = new SearchExecutor();
queries.Add("local", query1);
using (KeywordQuery query2 = new KeywordQuery(site))
{
query2.QueryText = "title:\"SharePoint\"";
query2.RowLimit = 100;
Source remoteSource = GetSearchSource("Twitter");
query2.SourceId = remoteSource.Id;
queries.Add("remote", query2);
results = se.ExecuteQueries(queries, true);
foreach (KeyValuePair<string,ResultTableCollection> result in results)

{
if (result.Value.Count > 0 && result.Value.QueryErrors.Count() == 0)
{
var resultTable = result.Value.Filter("TableType",
KnownTableTypes.RelevantResults);
if (resultTable != null && resultTable.Count() == 1)
{
tableResults = new DataTable();
tableResults.Load(resultTable.First(),
LoadOption.OverwriteChanges);
searchResults.Add(result.Key, tableResults);
}
}
}
}
}
}
return searchResults;
}
Demonstration: Server Side Object Model

This demonstration shows how to make search queries by using server-side code.
Demonstration Steps
3. Open a File Explorer window and browse to the E:\Democode\SearchWinApp folder.
4. Double-click the SearchWinApp.sln.

5. Open the Form1.cs code page.
6. Review the button1_click method. Notice that the calls are being made by using the Server Side
Object Model. Note that you could get back multiple result tables.
7. Press F5 to run the program.
8. Type Contoso in the text box.

9. Click Search. You should get results back in the grid view.
10. Close Visual Studio.
Executing Client-Side Queries

Provider-hosted apps can use client-side .NET
assemblies that proxy the search calls from the
client to the server. The client-side search APIs
exists in the
Microsoft.SharePoint.Client.Search.dll assembly.
Similar to the Server Side Object Model, the class
name is KeywordQuery but it resides in the
Microsoft.SharePoint.Client.Search.Query
namespace. You can see an example of how to do
this in the following code snippet:
The following code example shows how to use the

client-side object model to execute queries:
Code to Execute a Client-Side Query

ClientContext ctx = new ClientContext("http://search.contoso.com");
KeywordQuery kq = new KeywordQuery(ctx);
kq.QueryText = "SharePoint";
SearchExecutor = new SearchExecutor(ctx);

ClientResult<ResultTableCollection> results = searchExecutor.ExecuteQuery(kq);
ctx.ExecuteQuery();
The client-side object model also provides the ability to execute multiple search queries at once. You
simply create more instances and add them to a generic dictionary that is passed to the ExecuteQueries
method. You can also use the KeywordQuery to specify the result source on which you want to execute
the query. You can use the GetSearchSource method to find a result source by name and then set the
SourceId property on the KeywordQuery class.
When you execute a query in an app, by default the query will run in the context of the app. The
implication of this is to restrict result sets based on the app principal, rather than the user principal. Often
you will want queries to run in the context of the user rather than the app. To enable queries to run in the
context of the current user rather than the app, you must specify the QueryAsUserIgnoreAppPrincipal
permission scope. When you use the QueryAsUserIgnoreAppPrincipal permission scope, the search
service will provide search results that the app would not otherwise have permission to access.
Demonstration: Client Side Object Model

In this demonstration, you will see how to make search queries by using the client-side object model.
Demonstration Steps
3. Open an explorer window to the E:\Democode\SearchClientApp.
4. Double-click the SearchClientApp.sln.
5. Open the Form1.cs code page.
6. Review the button1_click method. Notice that the calls are being made by using the Client Side
Object Model classes that look exactly like the service-side object model. Also point out the possibility
of getting multiple result tables back.
7. Press F5 to run the program.
8. Type Contoso in the text box.
9. Click Search. You should get results back in the grid view.
Executing Representational State Transfer (REST) Queries

SharePoint provides a REST API for many common
operations, including Search. Behind the scenes, the
client-side object model is really making calls to
these APIs on your behalf, which are then directed
to the server-side object model. You can directly
execute a REST Search query by going to the
following URL for any site:
http://server/_api/search/query?querytext='sharepo
int'
When you make a call to the Search REST service,

you specify query parameters with the request.
With a GET request, you specify the query
parameters in the URL. For POST requests, you pass the query parameters in the body in JavaScript Object
Notation (JSON) format.
Common Search REST Endpoints

The following is a list of common end points that you can use to work with SharePoint Search.
 Execute a search query http://server/_api/search/query?querytext='sharepoint’

 Get Search suggestions http://server/_api/search/suggest?querytext='sharepoint'
 To use a search template

http://server/_api/search/query?querytext='sharepoint'&querytemplate='{searchterms}
title:sharepoint''
 To target a specific result source

http://server/_api/search/query?querytext='sharepoint'&sourceid='8413cd39-2156-4e00-b54d-
11efd9abdb89’
 To limit number of rows in search

http://server/_api/search/query?querytext='sharepoint'&rowlimit=30
Additional Reading: For more information on the available properties and endpoints, see
SharePoint Search REST API overview at http://go.microsoft.com/fwlink/?LinkId=321935.
The following code example shows you how to execute search queries by using REST:
Executing REST Search Queries

HttpWebRequest req = (HttpWebRequest)WebRequest
.Create("http://intranet.contoso.com/_api/search/query?querytext='" +
this.textBox1.Text + "'");
req.Method = "GET";
req.Accept = "application/atom+xml;odata=verbose";
req.ContentType = "application/atom+xml;odata=verbose";
req.Credentials = System.Net.CredentialCache.DefaultCredentials;
try
{
WebResponse res = req.GetResponse();
XDocument oDataXML = XDocument.Load(res.GetResponseStream(), LoadOptions.None);
XNamespace atom = "http://www.w3.org/2005/Atom";
XNamespace d = "http://schemas.microsoft.com/ado/2007/08/dataservices";
XNamespace m = "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata";
List<XElement> items = oDataXML.Descendants(d + "query")

.Elements(d + "PrimaryQueryResult")
.Elements(d + "RelevantResults")
.Elements(d + "Table")
.Elements(d + "Rows")
.Elements(d + "element")
.ToList();
var searchResults = from item in items

select new
{
Title = item.Element(d + "Cells").Descendants(d + "Key")
.First(a => a.Value == "Title").Parent.Element(d + "Value").Value,
Author = item.Element(d + "Cells").Descendants(d + "Key")
.First(a => a.Value == "Author").Parent.Element(d + "Value").Value,
HitHighlightedSummary = item.Element(d + "Cells").Descendants(d + "Key")
.First(a => a.Value == "HitHighlightedSummary").Parent.Element(d +
"Value").Value,
Path = item.Element(d + "Cells").Descendants(d + "Key")
.First(a => a.Value == "Path").Parent.Element(d + "Value").Value
};
this.dataGridView1.DataSource = searchResults.ToArray();
this.dataGridView1.Refresh();
}
Demonstration: Executing FQL Queries

In this demonstration, you will see how to use FAST Query Language (FQL) to execute search queries.
Demonstration Steps
3. Open a browser window to the following URL:
http://search.contoso.com /_api/search/query?querytext='Sharepoint'&enablefql=true
4. You should get an HTTP 500 error, because the default result source has a KQL query expression as its
query transform.
5. In a new browser tab, open SharePoint Central Administration.
6. Click Manage service applications.

7. Click Contoso Search
8. In quick launch, click Result Sources.
10. For the name, type FQL
11. Remove the Query Transform text {searchTerms} so it is blank.
12. Click Save.

13. In the dropdown for the FQL result source, click Set as default.
14. Switch to the first browser tab, then press F5 to refresh the page. You should now see results using
the FQL query.
15. Switch back to SharePoint Central Administration.
16. Set the Local SharePoint Results result source as the default.
Lab: Executing Search Queries from SharePoint Apps

Scenario
The management team at Contoso is concerned about the proliferation of duplicate content across the
new intranet portal. The team wants to provide a way for users to check, given a particular document,
whether similar content exists elsewhere on the portal. To implement this functionality, you will create an
app that uses client-side search APIs to query the search index for similar content. In addition to using the
client applications, they would also like to be able to find items based on metadata, but without having to
type the queries. They would like you to add a custom action to the menu items to redirect to the client
app.
Objectives
 Submit search queries.
 Create a SharePoint App that uses the REST API to retrieve search results.
 Understand how to use the REST Search APIs.
 Create a custom action that redirects to the SharePoint App.
Lab Setup
 User name: CONTOSO\administrator
Exercise 1: Submitting Search Queries from Client-Side Code

Scenario
In this exercise you will create a SharePoint App that will use the Search REST API and display search
results.
1. Create a New SharePoint App
 Task 1: Create a New SharePoint App

1. Connect to the 20489B-LON-SP-03 virtual machine.
2. If you are not already logged on, log on to the LONDON machine as CONTOSO\Administrator with
password Pa$$w0rd.
3. Create a new App for SharePoint project named SearchApp in the E:\Labfiles\Starter folder. The
project should:
a. Use the SharePoint-hosted app model.
b. Use the developer site at http://dev.contoso.com for debugging.

4. Open the default.aspx page and delete all the markup within the PlaceHolderMain content control.
5. Add the following HTML controls to the content control:
a. A text box with an id value of txtSearch.
b. A button with an id value of btnSearch.
c. A div element with an id value of search-title.
d. A div element with an id value of search-results.
6. Open the App.js file, and delete the contents of the file.
7. Add the following variable declarations to the top of the file:
var context;
var web;
var user;
var currentItem;
var hostweburl;
var appweburl;
var title;
8. Add the following utility code to parse query string parameters:
function getQueryStringParameter(paramToRetrieve) {
var params =
document.URL.split("?")[1].split("&");
var strParams = "";
for (var i = 0; i < params.length; i = i + 1) {
var singleParam = params[i].split("=");
if (singleParam[0] == paramToRetrieve)
return singleParam[1];
}
}
function GetListId() {
return decodeURIComponent(getQueryStringParameter("ListID"));
}
function GetHostSiteUrl() {
return decodeURIComponent(getQueryStringParameter("SPHostUrl"));
}
function GetAppSiteUrl() {
return decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));
}
function GetItemId() {
return getQueryStringParameter("ItemID");
}
9. Add a function named getSearchResults. The function should accept a single argument named
queryText.
10. Within the getSearchResults function, add code to display the text Search results for [queryText],
where queryText is the value of the queryText parameter, in the search-title div element.
11. Construct a URL that uses the REST API to submit the query text to the search service. You should
construct this URL by concatenating:
a. The URL of the app web.
b. The REST API endpoint for the search service.

c. The query text as a query string parameter.
12. Instantiate a new SP.RequestExecutor instance named executor. Pass in the URL of the app web as
an argument to the constructor.
13. Call the executeAsync method on the executor object to send an HTTP GET request to the URL you
constructed. The method should:
a. Call a callback handler method named onGetSearchResultsSuccess if the request was successful.
b. Call a callback handler method named onGetSearchResultsFail if the request returns an error.
14. Add a function named onGetSearchResultsSuccess. The function should accept a single argument
named data.
15. Add a function named onGetSearchResultsFail. The function should accept arguments named data,
errorCode, and errorMessage.
16. In the onGetSearchResultsSuccess function, add the following code to parse the returned JSON and
display the search results:
var jsonObject = JSON.parse(data.body);

var results =
jsonObject.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results;
if (results.length == 0) {
$('#search-results').text('No items were found');
}
else {
var searchResultsHtml = '';
$.each(results, function (index, result) {
searchResultsHtml += "<a target='_blank' href='" +
result.Cells.results[6].Value + "'>" + result.Cells.results[6].Value + "</a><br/>";
});
$("#search-results").html(searchResultsHtml);
}
17. In the onGetSearchResultsFail function, add the following code to display an error message to the
user.
$('#search-results').text('An error occurred during search - ' + errorMessage);
18. Save your work.

19. Edit the app manifest file to request the following permissions:
a. The QueryAsUserIgnoreAppPrincipal permission at the Search scope.
b. The Read permission at the Web scope.
20. Save your work, and then start debugging.
21. On the Do you trust SearchApp page, click Trust It.
22. On the SearchApp page, in the search text box, type Contoso, and then click Go. You should see
results presented in the app web page. This may take one to two minutes.
Note: Complete sample code for the App.js file is available in the
E:\Labfiles\Starter\App.js file.
Results: A new SharePoint App that uses Search REST API calls.
Exercise 2: Using a Custom Action to Launch A Search App

Scenario
In this exercise you will create a custom action and integrate it with the SharePoint App that you just
created to automatically perform a search based on the metadata of an item.
1. Add a Custom Action to Call App Page
2. Test the Custom Action and Search App
 Task 1: Add a Custom Action to Call App Page

1. In Visual Studio, add a new Menu Item Custom Action named SearchAction to the project.
2. Specify that the custom action should be exposed on the host web.
3. Set the scope of the custom action to List Template, and specify a specific scope of Document
Library.
4. Set the menu item text to Search.
5. Ensure the navigation URL is set to SearchApp/Pages/Default.aspx.

6. In the element manifest file for the custom action, in the UrlAction element, change the value of the
Url attribute to the following:
~appWebUrl/Pages/Default.aspx?{StandardTokens}
&HostUrl={HostUrl}&Source={Source}
&ListURLDir={ListUrlDir}
&ListID={ListId}&ItemURL={ItemUrl}&ItemID={ItemId}
7. Save your work.

8. In the App.js file, immediately below the line of code that loads the SP.RequestExecutor.js file, load
the current list item (in other words, the list item that the user was viewing when they clicked your
menu item).
Note: You will need to start by loading an SP.Web object that represents the host web.
Use the utility methods in the App.js file to retrieve ID values for the list and the list item.
9. Using the title of the current list item as the query text, submit a search query using the code you
developed in the previous exercise.
10. Save your work, and then use Visual Studio to deploy the search app.
11. When prompted, trust the search app. You will test the app in the next task.
 Task 2: Test the Custom Action and Search App

1. Open the developer site and browse to the Documents library.
2. Use the Northwind Traders Contract.docx document to test your new custom action.
3. On the Documents page, on the Northwind Traders Contract row, click the ellipsis.
4. In the Northwind Traders Contract.docx dialog box, click the ellipsis, and then click Search. You
will be redirected to the App web page and a search is performed based on the Title of the
document.

Note: At this point, the app is designed to run only when a user clicks the custom action
menu item labeled Search. If you try to debug the app directly, you will see a JavaScript error
because there is no list item associated with the app. You must deploy the app and launch it from
the Edit Control Block on a document.
Results: A new custom action that directs to a SharePoint App.


In this module, you learned about the search architecture’s various roles and how the search index works.
You also explored the search schema and how it contains items including crawled and managed
properties. You gained insights into the search schema in SharePoint 2013, and you learned how
administrators can modify search settings for sites and site collections.
You learned about the two search query languages, Keyword Query Language and FAST Query Language.
Finally, you were shown how to submit those queries through the various SharePoint search APIs,
including Web Services, Server Object Model, Client Object Model, and REST Services.
Review Question(s)
Test Your Knowledge

Question
Which of the following is not run by the NodeRunner.exe process?
Select the correct answer.
Administration
Content Processing
Analytics
Crawler
Index
Test Your Knowledge

Question
Which of the following search queries will return all Word documents modified after
1/1/2013?
Docx AND 1/1/2013
Title:Docx AND 1/1/2013
FileType:Docx AND Modified>=1/1/2013
FileType:Word AND Write>=1/1/2013
FileType:Docx And Write <=1/1/2013

Test Your Knowledge

Question
What is the maximum query length of a search query when using the user interface?
1,024
512
2,048
4,096
256
Test Your Knowledge

Question
What permission does an App for SharePoint need in order to execute search queries?
Search, QueryAsUserIgnoreAppPrincipal
Web, FullControl
Site Collection, FullControl
Enterprise Resources, Read
Tenant, FullControl
4-1
Module 4
Customizing the Search Experience
Contents:
Module Overview 4-1
Lesson 1: Customizing Query Processing 4-2
Lesson 2: Customizing Search Results 4-16
Lab A: Configuring Result Types and Display Templates 4-27
Lesson 3: Customizing Content Processing 4-30
Lab B: Configuring Entity Extraction 4-38
Module Overview
Microsoft® SharePoint® 2013 provides an out-of-the-box search experience that is adequate for many
uses. However, there are several scenarios where administrators and developers will want to customize the
Search Center, the Search Center pages, which results are displayed, and how results are displayed. In this
module, you will learn how to customize various aspects of the search experience, including how
SharePoint processes queries, how search results are presented to the user, and how SharePoint processes
crawled content prior to indexing.
Objectives
 Customize query processing by creating and configuring result sources, query transforms, and query
rules.
 Customize search results by creating and configuring search pages, search web parts, result types,
display templates, and refiners.
 Customize content processing by configuring entity extractors, thesauri, and content enrichment web
services.
4-2 Customizing the Search Experience
Lesson 1
Customizing Query Processing
In the past, search would simply handle a user or application keyword query and present a set of results
from a single source, such as SharePoint, in a static format. Search technologies have evolved to allow
multiple result sources, providing the display of rich content results with the ability for each result to have
a custom look and feel. This lesson will teach you how SharePoint Search performs these types of tasks
and the control you have over customizing the query process via programmatic interfaces.
Lesson Objectives
 Create result sources.
 Create query transforms.
 Understand keyword and property filters in query transforms.

 Understand sorting in query transforms.
 Create query rules.
 Understand query rule conditions and actions.
 Export and import search settings.
Result Sources
SharePoint Search gathers content from content
sources that search administrators have configured.
These sources can be of any type and in any
number of places. Out-of-the-box SharePoint
Search can connect to SharePoint, File Shares,
Exchange, and many more sources. As a developer,
you can enhance search to implement Business
Connectivity Connectors to index any content that
resides on your network. The Search Gatherer
gathers content that resides in these sources and
put it into the index. No matter where the content
comes from, its crawled properties end up in the file
system-based index in a common format.
Once in the index, you can create Result Sources that partition the data based on managed properties. In
this way, result sources limit searches to certain content or to a subset of search results. Result Sources
support the following protocols:
 Local SharePoint
 Remote SharePoint
 OpenSearch 1.0\1.1 feeds
 Exchange 2013 web services protocol

OpenSearch
Not only are Result Sources used to partition SharePoint content, but they are also used to implement
search federation. Search federation is used to display results from external search systems. Because of the
support of OpenSearch, you can create a Result Source that targets external systems like Bing, Twitter, and
many more.
Common OpenSearch end points include:
 Twitter: http://twitter.com/search?q={searchTerms}
 Bing: http://www.bing.com/search?q={searchTerms}
Query Transforms
In addition to a protocol, Result Sources can be configured with Query Transforms to implement the
partitioning mentioned above. These Query Transforms can be manually typed in or, in most cases due to
ease of use, be created by using the Query Builder tool. Like regular search queries, Query Transforms can
be simple or very complex. The real power of Result Sources comes from the Query Transforms applied to
them.
Authentication
Lastly, you can set up a username and password for basic authentication to external sources in Result
Sources.
Result Source Usage

Although you can create many result sources, it is important to note that each search result page, by
default, has only one Search Results web part. Each Search Result web part can have only one result
source configured at a time. If you want to show other results in a single page, you will need to either add
a second Search Results web part, or implement query rules to supplement the respective query results in
the single Search Result web part. Both of these concepts are explored later in this module.
Default Result Sources

Out of the box, SharePoint provides 16 pre-configured result sources configured at the search service
application level. These include:
 Conversations. Discussions in microblogs, newsfeed posts, and community sites.
 Documents. Microsoft® Office documents and PDF documents.
 Items matching a content type. Items that match a content type that the incoming query specifies.
 Items matching a tag. Documents or list items that match a managed metadata term.
 Items related to current user. Documents or list items that are related to the user.
 Local People Results. People items from the profile database of the User Profile service application.
 Local Reports and Data Results. Excel®, Office Data Connection (ODC), or Report Definition Language
(RDL) items, or items in a report library.
 Local SharePoint Results. All items from local SharePoint search index except People.
 Local Video Results. Videos.
 Pages. SharePoint web pages.
 Pictures. Photos and images.
 Popular. Documents and list items sorted by view count.
 Recently changed items. Documents and list items sorted by modified date.
 Recommendations. Documents and list items that you recommend for the incoming query.
 Wiki. SharePoint wiki pages.
You can set any result source as the default result source. When you add a Content Search Web Part to a
page, the Web Part automatically uses the default result source.
Creating Result Sources

SharePoint Search architecture has been modified
to allow Farm Administrators, Site Collection
Administrators, and Site Administrators to create
Result Sources. You can create results sources via
the Search Service Application management page,
the Site Collection Administration settings, or the
Site Administration settings page. You can also
create result sources programmatically. This is
helpful when rebuilding an environment after a
disaster, building a disaster recovery farm or a
development farm.
When creating a Result Source, at what level you
create the Result Source determines who can see it. At the highest level is the Service Application,
followed by site collection and site. When creating a Result Source at the Service Application level, all site
collections and sites can see it. When creating at the Site Collection level, all sites in that site collection can
see it. When created at the site level, only the site can see it.
The following code example shows how to create a new result source:
Creating a Result Source

using (SPSite site = new SPSite("http://teams.contoso.com"))
{
SPServiceContext context = SPServiceContext.GetContext(site);
// Get the search service application proxy.

context.GetDefaultProxy(typeof(SearchServiceApplicationProxy)) as
SearchServiceApplicationProxy;
// Get the search service application info object so we can find the Id of our Search
Service App.
SearchServiceApplicationInfo ssai = searchProxy.GetSearchServiceApplicationInfo();
// Get the application itself.

SearchServiceApplication application =
Microsoft.Office.Server.Search.Administration.SearchService.Service.SearchApplications
.GetValue<SearchServiceApplication>(ssai.SearchServiceApplicationId);
Microsoft.Office.Server.Search.Administration.Query.FederationManager fedManager = new

Microsoft.Office.Server.Search.Administration.Query.FederationManager(application);
// Specify the search schema level.

SearchObjectOwner owner = new SearchObjectOwner(SearchObjectLevel.SPSite,
oSPsite.RootWeb);
Source currentResultSource = fedManager.CreateSource(owner);

currentResultSource.Name = "Exchange Result Source";
currentResultSource.ProviderId = fedManager.ListProviders()["Exchange Search

Provider"].Id;
currentResultSource.Commit();
}
As you can see from the code example, you need several pieces of information to set up a result source.
The main piece of information is the owner, and the second most important is the Provider ID. The valid
provider keys are:
 Best Bet Provider
 Exchange Search Provider
 Local People Provider
 Local SharePoint Provider
 OpenSearch Provider
 Personal Favorites Provider
 Remote People Provider
 Remote SharePoint Provider

You can also create result sources by using Windows PowerShell, but it must be done via regular .NET
assembly loading and not by using a specific cmdlet.
The following code example shows how to create result sources by using Windows PowerShell:
Creating Result Sources with Windows PowerShell

# get current search service application
$searchApp = Get-SPEnterpriseSearchServiceApplication;
$site = get-spsite http://search.contoso.com
# load Search assembly

[void] [Reflection.Assembly]::LoadWithPartialName("Microsoft.Office.Server.Search")
# create manager instances

$fedManager = New-Object
Microsoft.Office.Server.Search.Administration.Query.FederationManager($searchApp)
$searchOwner = New-Object
Microsoft.Office.Server.Search.Administration.SearchObjectOwner([Microsoft.Office.Server.
Search.Administration.SearchObjectLevel]::Ssa, $site.RootWeb)
# define query
$query = '{searchTerms?}'
$resultSource = $fedManager.CreateSource($searchOwner)
$resultSource.Name = 'My Custom Source'
$resultSource.ProviderId = $fedManager.ListProviders()['Local SharePoint Provider'].Id
$resultSource.CreateQueryTransform($query)
$resultSource.Commit()
$site.dispose()
Query Transforms
A result source is defined by the Query Transform
that is applied on it. A Query Transform interprets a
user’s query and to modify it to provided targeted
results. A Query Transform is made up of two main
parts:
 Query Filter
 Sorting
Query Filter
A query filter is simply a query based on a set of
parameters passed into it or manually set. It can be
made up of Keyword and Property Filters.
Sorting
You can sort the result source based on a set of managed properties, a ranking model, or dynamic
ordering rules.
Query Transformation and Processing

A user’s query is transformed in the following very specific order:
1. Any web part based modifications are applied.
2. Any query rules are applied.
3. Any query transform in the result source.
The last item to modify a query is the query transform in the result source. These changes are always
applied.
Query Transforms - Keyword Filters

A Query Transform’s key property is the query that
has been configured upon it. This Query Transform
can take values from the context of where the
query is being performed and pass them into the
query component for processing. Keyword filters
are used to add predefined query variables to the
query transform. You can add the following
Keyword Filters:
 Query after all transformations. This is the

default keyword filter and simply passes in the
keyword text that was submitted from the user
or application.
 Query from the search box. This takes the value from the connected search box web part on a search
results page.
 Name of the user who runs the query. This will pull the current SPUser’s name from the Query context
and pass it into the query.
 Value of a parameter from URL. This allows you to pull a value from the QueryString of the Search
Results page URL and pass it into the query.
 Value of a token from URL. A value from a URL token.
 Value of a field on the page. A value from a page field.
 Only return sites. Adds a managed property search that tells search to query only for sites.
 Only return lists and libraries. Adds a managed property search that tells search to query only for lists
or libraries.
 Only return items. Adds a managed property search that tells search to query only for list items.
Query Transforms - Property Filters

In addition to keyword filters, some of which are
property filters, you can add other custom
Managed Property filters. You can use property
filters to query the content of managed properties
that are set to queryable in the search schema. By
using property filters, you can narrow the indexed
content to match the purpose of the result source.
Some examples include:
 Target a particular file type.
 Narrow down on a particular term.

 Choose a date range (most recent or oldest).
 Find document by a particular author.
 Find items that have a high click through rate.

 Find highly ranked items.
As you can see, the possibilities for the type of result source you can build are limited to your metadata
and imagination.
Query Transforms - Sorting

Your results can be sorted in any way you like. The
most common way of sorting results source results
is by a managed property. You can sort on any
managed property that has the Sortable property
checked.
Some examples of ways to sort your result source

results include:
 By Author
 By Content Class (Site, List, ListItem)
 By Content Type
 By Modified Date
 By Tag
 By Path
 By Title
Sort Levels
You don’t have to base the sort on a single property; instead, you can have several levels of sort. For
example, you can sort by the title first and then the modify date, or sort first by the modify date and then
the author.
Ranking Models
You can also select one of the 15 built-in ranking models. The default search model is based on the
industry-standard BM25 ranking function. These models include:
 Default Search Model
 Custom Search Model
 Catalog ranking model
 Recommender ranking model

 People Search expertise social distance ranking model
 Site suggestion ranking model
 Search Model with Boosted Minspan

 People Search social distance model
 People Search expertise ranking model
 People Search name social distance ranking model
 People Search name ranking model
 Popularity ranking model
 O14 Default search Model

 People Search application ranking model
 Search Model Without Minspan
Dynamic Ranking
As a final step in sorting, you can specify a Dynamic Ordering Rule. This rule enables you to promote
items based on several conditions. These conditions include:
 Title contains keywords
 Title matches keywords
 URL starts with
 URL exactly matches

 Content Type is
 File Extension matches
 Results has the tag

 Manual condition
If the condition matches, you can do any number of promotions, including:

 Promote to top
 Promote by 1-10
 No change
 Demote by 1-10
 Demote to bottom
Creating and Configuring Query Transforms

The most common and simple way of creating
Query Transforms is by using the Query Builder.
However, you can also create Query Transforms
programmatically. This requires you to build a
query transform by passing in an optional
QueryTransformProperties object and a required
query template.
The QueryTransformProperties is a dictionary of

items that override the way the query is applied.
The most common properties are used to set the
sorting on a query. For example, the following value
will set the LastModifiedTime managed property to
be sorted in descending order:
{[SortList, LastModifiedTime:Descending]}
The available properties that can be added to the QueryTransformProperties are not well documented,
but you can get a good idea of what they are by evaluating the out-of-the-box Result Sources. Another
method is to simply build some queries with the Query Builder and then review the QueryTransform
object that is generated.
Once you have constructed your QueryTransformProperties object, you can optionally pass it in with
your query template to the CreateQueryTransform method of the Result Source. This method has two
overrides and does not need a QueryTransformProperties object. After creating the QueryTransform,
you need to call the Commit method on the Result Source to save the changes.
The following code example shows how to create a query transform programmatically:
Creating a Query Transform

{
// Get the search service application proxy

Service App
SearchServiceApplicationInfo appInfo = searchProxy.GetSearchServiceApplicationInfo();
Microsoft.Office.Server.Search.Administration.SearchService.Service
.SearchApplications.GetValue<SearchServiceApplication>(appInfo.SearchServiceApplicationId
);
oSPsite.RootWeb);
Source customSource = fedManager.GetSourceByName("My Custom Source", owner);

QueryTransformProperties qtProps = new QueryTransformProperties();
SortCollection sortCollection = new SortCollection();
sortCollection.Add("LastModifiedTime", SortDirection.Descending);
qtProps["SortList"] = sortCollection;
customSource.CreateQueryTransform(qtProps, "{searchTerms}");
customSource.Commit();
}
The following code example shows how to modify an existing query transform:
Modifying a Query Transform

{
// Get the search service application proxy

Service App
SearchServiceApplicationInfo appInfo = searchProxy.GetSearchServiceApplicationInfo();
Microsoft.Office.Server.Search.Administration.SearchService.Service
.SearchApplications.GetValue<SearchServiceApplication>(appInfo.SearchServiceApplicationId
);
oSPsite.RootWeb);
Source customSource = fedManager.GetSourceByName("My Custom Source", owner);

customSource.QueryTransform.OverrideProperties = null;
customSource.QueryTransform.QueryTemplate = "";
customSource.Commit();
}
Demonstration: Creating Result Sources with Query Transforms

The instructor will now demonstrate how to add result sources to the various ownership levels by using
different types of query transforms.
Demonstration Steps
3. On the Windows® Start page, click Internet Explorer.

4. In the address bar, type http://team.contoso.com, and then press Enter.
5. On the Contoso Team Site home page, click Settings, and then click Site settings.
6. Under Site Collection Administration, click Search Result Sources.
7. On the Manage Result Sources page, click New Result Source.
8. In the Name box, type My Custom Source.
9. Notice that you are not setting the Query template, and then click Save.
10. On the Windows Start page, click Computer.
11. In File Explorer, browse to E:\Democode\CreateQueryTransform, and then double-click

CreateQueryTransform.sln.
12. In the How do you want to open this type of file (.sln) dialog box, click Visual Studio 2012.
13. In Visual Studio®, in Solution Explorer, double-click Program.cs. Review the code, and notice each of
the steps that are required to get a Search context and that this result source is scoped at a site
collection level. Note the way to create the QueryTransformProperties object. Notice that after all
items have been set, you make a call to Commit to save your changes.
14. On the DEBUG menu, click Start Debugging.
15. Switch to Internet Explorer.
16. Click the My Custom Source result source. Notice that the Query template is now populated, and
then click Launch Query Builder.
17. In the Build Your Query dialog box, click the SORTING tab, notice that the sort is now based on the
LastModifiedTime in descending order, and then click Cancel.
18. Close Internet Explorer, and then close Visual Studio.

Query Rules
Query rules are used to attempt to capture the
intent of a user query. When executed, they return
results that better match that intent. This is new
functionality that was not available in SharePoint
2010. Each query rule is made up of four main
parts:
 Scope\Context
 Query Conditions
 Query Actions
 Publishing Settings
Scope\Context
Each query rule is tied to a specific scope. This scope can be based on:
 Result Source. You can target all result sources or a specific result source.
 Categories. A page category based on cross-site publishing and metadata navigation.
 User Segments. You can target particular users that have certain metadata tags associated with them
(Department, Job Title, Location).
Note: Query Rules are the replacement for keywords in SharePoint 2010. When upgrading
to SharePoint 2013, keywords are automatically converted to Query Rules.
Publishing Settings
You can set a query rule to apply during a set timeframe. By default, a rule will be active until you
manually deactivate it. Deactivating a rule is done on the Query Rule administration page via the drop-
down list. Some examples of how you can use the publishing settings are:
 A sales promotion for a short period of time
 Internal event should be shown for set period of time
Query Rule Group Ranking

You may find that multiple query rules are firing at multiple levels. You can configure the rules into
groups and then order the groups to control the execution order. You can also tell the rules to stop
executing as part of the ranking.
Query Rule Conditions and Actions

Query Rules are made up of conditions and actions.
Utilizing these condition and actions is the main
way to change the behavior of a user’s query.
Query Conditions
Aside from the Query Rule scope, you must set up
Query Conditions. When these conditions evaluate
to true, the Query Rule actions will execute. Query
Rules can be any of the following:
 Query matches keyword exactly
 Query contains action term
 Query matches dictionary exactly
 Query more common in source

 Result type commonly clicked
 Advanced query text match
Query Actions
When a Query Condition evaluates to true, you can have any one of the following actions execute:
 Add promoted results. This is a result that will appear at the top of the search results, and is similar to
keywords and best bets in 2010.
 Add result blocks. This is a result set that is embedded in the default result set and will show at the top
of the results, or can be integrated into the core results. This is similar to how federated searches
worked in SharePoint 2010.
 Change ranked results by changed the query. This can be used to add query filters to a user’s search
query to further refine what they are looking for based on past search results and user feedback.
Demonstration: Query Rules

The instructor will now demonstrate how to create and configure a query rule by using the SharePoint
2013 user interface.
Demonstration Steps

3. On the Windows Start page, click Internet Explorer.
4. In the address bar, type http://search.contoso.com, and then press Enter.
5. Click Settings, and then click Site settings.
6. Under Site Collection Administration, click Search Query Rules.
7. On the Manage Query Rules page, in the Select a Result Source list, click Local SharePoint
Results (System).
8. Click New Query Rule.

9. On the Add Query Rule page, in the Rule name box, type SharePoint.
10. Click the Context link to expand the context configuration section.
11. Under Query is performed on these sources, click All sources.
12. In the Query Conditions section, in the Query exactly matches one of these phrases (semi-colon
separated) box, type SharePoint.
13. In the Actions section, click the Add Promoted Result link.
14. In the Add Promoted Result dialog box, in the Title box, type Microsoft SharePoint.
15. In the URL box, type http://www.microsoft.com/sharepoint, and then click Save.
16. On the Add Query Rule page, click the Publishing link to expand the publishing section.
17. For the Start Date, click the calendar icon, and then click today’s date.
18. For the End Date, click the calendar icon, click one week from today, and then click Save.
19. Click the Contoso Search link.
20. On the Search homepage, in the text box, type SharePoint, and then press Enter. You should see the
promoted result at the top of the page.
Importing and Exporting Search Schemas

There may come a time when you need to export
the search schema configuration of a site and
import it into another site. This can be
accomplished via the UI and programmatically. This
enables you build your search customizations in a
development environment and then move the
settings into production. It is also handy for having
a backup in case you have to rebuild the
environment later.
The following code example shows how to export

the search schema settings of a SharePoint site
programmatically:
Export the Search Schema Settings of a Site

{
// Pick the search schema level.
site.RootWeb);
// Create a new SearchConfigurationPortability object.

SearchConfigurationPortability port = new SearchConfigurationPortability(site);
// Export the configuration.

string export = port.ExportSearchConfiguration(owner);
File.AppendAllText("c:\temp", "SearchExport.xml");
}
The following code example shows how to import a search schema into a SharePoint site
programmatically:
Import a Search Schema

{
// Pick the search schema level.
oSPsite.RootWeb);
// Create a new SearchConfigurationPortability object.

SearchConfigurationPortability port = new SearchConfigurationPortability(site);
// Read in a configuration file.

string import = File.ReadAllText(@"c:\temp\SearchExport.xml");
// Import a configuration.
port.ImportSearchConfiguration(owner, import);
}
You can export and import result sources, query rules, result types, ranking models, and search settings at
the site collection or site level. You can also export search settings from a Search service application and
import the settings into a site collection. However, you cannot import search settings into a Search service
application.
Discussion: Result Sources and Query Rules

What Result Sources can you see your organization
creating and what type of Query Rules would you
configure on them?
Lesson 2
Customizing Search Results
In this lesson you will learn how to customize the search experience of the result pages. This includes the
pages they use to submit their queries and the result pages that display their results. Each result can be
classified by using result types, which then can be customized to be shown in various ways by using
display templates. Finally, if users are presented with hundreds of thousands of results, they will need a
way to narrow the results by using out-of-the-box and custom refiners.
Lesson Objectives
 Create custom Search Pages.
 Modify Search Navigation.
 Create and modify result types.

 Create and modify display types.
 Create and modify refiners.
 Work with the Content Search web part.
Search Pages and Navigation

When a user submits a query, they typically do so
on a Search Center site. The query is then sent to a
results page where several web parts interact to
provide a set of results. There are four default
search result pages in the Search Center. Each of
these maps to a specific tab in the Search
Navigation. The default tabs are:
 Everything (results.aspx)
 People (peopleresults.aspx)
 Conversations (conversationsresults.aspx)
 Videos (videoresults.aspx)
Each of these pages has the same set of web parts:
 Search Box
 Search Navigation
 Search Results
 Refinement
The only difference between each of these pages is the way the web parts are configured. The main
configuration difference is the Search Results web part. It has a different result source targeted for each
page, and as a result, you see targeted results when you are viewing each respective page.
Search Results Web Part

The Search Results web part is one of the most
important web parts in the set of Search web parts.
It is what takes the user query and then displays the
various results on a search result page. Each Search
Result web part has a Search query property. You
can modify this query property by editing the web
part and configuring it by using the Query Builder.
Similar to creating a Result Source, you define a set

of filters and the sorting properties of the query.
You also have extra configuration settings such as
refiners and query settings.
Query Settings
As part of the query settings, you can specify if you want Query Rules to execute on the search results.
You can also elect to have the URL rewritten for catalog pages (which are discussed in later modules).
Finally, you can have the web part submit the query when the page loads on the server side, or from the
browser after the page has loaded. The default is to execute the query from the browser, because this
makes it seem to the user that the page has loaded very quickly, even though results may not show up on
the page immediately.
Although you could programmatically update a web part on a web part page such as a results page, it is
not common to do so. It is typically done via the SharePoint UI and via the Query Builder dialog.
Result Types
When you have set up your content sources, search
will have indexed many different types of content,
from Adobe PDF files to Microsoft Word
documents. You will also index several types of
SharePoint content, including sites, HTML pages,
lists, list items, and many more. Each of these
different types of content should be displayed
differently. In the past, they were all displayed
exactly the same way: a title, a summary area, and a
link. You would then click on the link to view the
content wherever it resided and in the viewer
specific to that piece of content.
Search has evolved to provide a much more customized experience in which you see a different view of
the item based on its content type.
The way an item is rendered is based on Result Types. A result type is based on a particular type of
content. It has the following settings:
 Source
 Conditions
 Actions
Source
The source is any visible Result Source including the “All Sources” option.
Conditions
A condition uses a managed property and then an operator and value. If the condition evaluates to true,
then the action is performed. A condition can utilize the following operators:
 Equal and of
 Doesn’t equal any of
 Contains any of
 Doesn’t contain any of
 Less than all of
 Greater than all of
 Start with any of
As you can see, a condition can match against multiple values. Multiple conditions must be combined
with the “AND” operator.
Actions
An action will determine the display template that is used if the condition has been met.
Display Templates
Display templates enable you to design the way a
search result will render. This can be in the Search
results web part, the Content Search web part, or
any other web part that renders search results.
Display templates are simple HTML files that have
special JavaScript markup in them to tell SharePoint
how to render the managed properties of a result
item.
There are several different types of display

templates, these include:
 Control. Control Display Templates control the

organization of your results within the web part
they are used in, and the overall look of the web part. They are used in Content By Search, Search
Results, and Refinement web parts.
 Group. Group Display Templates are used to group together a number of Item Display Templates.
They can appear in Control Display Templates. They are used in the Search Results web part.
 Item. Item Display Templates enable you to specify which managed properties are used and how they
appear for a result. They are used by the Content By Search and Search Results web parts.
 Filter. Filter Display Templates enable you to create customized refinement controls that will appear in
the Refinement web part.
Once you have selected a display template type, you can then specify the types of controls that can use
the display template. This includes:
 SearchResults
 SearchHoverPanel
 Content Web Parts

 Refinement
 SearchBox
 Custom
SharePoint 2013 provides a wide range of out-of-the-box display templates for search, and you will
probably want to use these templates as the basis for your own custom templates. The Search-based
display templates live in the folder“/_catalog/masterpage/Display Templates/Search”. You should see
templates for the following:
 BestBets
 Common
 Community
 Default
 Discussion
 Excel
 MicroBlog
 Office Document
 OneNote
 PDF
 Person
 Personal Favorite
 Picture
 PowerPoint
 Reply
 Site
 Video
 WebPage
 Word
The easiest way to view and edit these files is via SharePoint Designer. There are several files in this
directory, however, you should see that for each .html file there is a corresponding .js file. This .js file is
built for you and is similar to how publishing from Word into HTML works via thicket files (a file with a
linked folder containing resources). Each time you edit the .html file, the .js is updated. You will also notice
that there is a specific naming convention used for the file names. For example, if you look at the Person
display template, you will see six files:
 Item_Person.html
 Item_Person.js
 Item_Person_CompactHorizontal.html
 Item_Person_CompactHorizontal.js
 Item_Person_HoverPanel.html
 Item_Person_HoverPanel.js
You should use the same naming standard that Microsoft uses when creating your display templates. In
the example above, all files start with Item_. This tells you that this is an Item display template. The next
part will be the name of the display template, in this case Person. The third part delimited by the
underscore character is a special helper display template. You can see both a CompactHorizontal and a
HoverPanel helper. These drive the hover callout of the result when you move the mouse over the result.
Note: The naming convention is not what determines where and how a display template is
used. It is determined by the content type that is applied and the metadata of the item. Also, the
use of the hover panel is set in the JavaScript of the display template.
Creating Display Templates

The easiest way to create a display template is to
simply copy one of the provided templates and
then modify it to your needs. Be sure to create it
with a meaningful name. As a best practice, you
should modify the .html markup so the name
matches the file name.
There are several properties stored in the HTML

markup of a display template. These include:
 Title
 TemplateHidden
 MasterPageDescription
 ContentTypeId
 TargetControlType
 HtmlDesignAssociated
 ManagedPropertyMapping
 Body
Each of these can be editing via the file, but it is also possible to do this through SharePoint UI by editing
the file properties when viewing it in the browser. When you change these in the UI, they will be updated
in the file.
The body of the display template is where the real work happens. As you can see in the code snippet
below, you will be passed a ctx variable that will contain all the information about the result item. You can
then write JavaScript code that will render the managed properties. It is important to point out that in this
template, you will see that it is rendering a div tag for each Word document. The div tag has an id
attribute and that attribute is set to the itemId of the search result item. This ensures that all your div tags
have a unique id and can be referenced easily by other JavaScript code that you might add to the display
template.
You will also notice that to switch in and out of code mode, you must use the “
</head>
<body>
<div id="Item_Word">

<div id="_#= $htmlEncode(itemId) =#_" name="Item" data-

displaytemplate="WordItem" class="ms-srch-item" onmouseover="_#=
ctx.currentItem_ShowHoverPanelCallback =#_" onmouseout="_#=
ctx.currentItem_HideHoverPanelCallback =#_">
_#=ctx.RenderBody(ctx)=#_
<div id="_#= $htmlEncode(hoverId) =#_" class="ms-srch-hover-
outerContainer"></div>
</div>

</div>
</body>
</html>
Demonstration: Display Templates

The instructor will now demonstrate how to create a new result type and how to associate display
templates with result types.
Demonstration Steps


6. Under Site Collection Administration, click Search Result Types
7. On the Manage Result Types page, click New Result Type.
8. On the Add Result Type page, in the Give it a name box, type Word Documents.
9. Click Show more conditions to expand the advanced conditions area.
10. In the Which custom properties should match? list, click FileType.
11. In the Enter value for property box, type doc.
12. Click the Add value link.
13. In the Enter value for property box, type docx.
14. In the What should these result look like? list, click Office Document Item, and then click Save.

Refiners
When a user submits a search query, they can be
presented with thousands of results. Based on the
default ranking model that SharePoint uses, the
item that they are looking for may not show up in
the first page of results. When this happens, they
need a way to drill down into what they are looking
for. This is called refining your results.
SharePoint search pages provides some very basic

refining capabilities based on:
 FileType
 ContentClass
 ContentTypeId
 WebTemplate
 DisplayAuthor
 LastModifiedTime
These are configured via the Refinement web part that exists on search result pages. By editing the
refinement web part, you can add any managed properties that have been configured to be an active
refiner. By default, managed properties do not have the Refinement property enabled. After enabling,
you must re-index your content in order to get any refinement values to display.
Refiner Properties
Each refiner has a series of properties. This includes:
 Type. Text, integer, datetime, and so forth.
 Aliases. Any alias set up on the managed property.
 Display name. The name that should be displayed to users. Note that some managed property names
are not very meaningful, and that this property enables you to override what is displayed.
 Display template. How the refiners will display. Text-based refiners are normally just a list, whereas
datetime-based refiners can show the date slider.
 Sort by. You can sort based on count, name, and number.
 Sort Direction. Ascending or Descending.
 Maximum number of refiner values. How many items should show in the refiner area.
Refinement Counts
Another interesting fact about refiners is that the refinement counts are not displayed by default. You
must enable these in the display templates.
Creating and Configuring Refiners

Creating a refiner starts with enabling the
Refinement check box on a managed property.
Once this has occurred, you must do a full crawl of
your content in order to populate the refiner with
values. There are two types of refinement properties
available for a managed property:
 Active
 Active latent
Active latent will do all the work necessary for the

refiner to be used at a later time, but will not
display it for use in the Refinement web part.
Note: Although you can create your own managed properties at the site collection level,
you cannot create managed properties that can be used as refiners. This must be done at the
service application level. Even if you were able to do this, you will still need a service application
administrator to run a full crawl for you in order to use your managed property.
Once you have created a refinement-based managed property, you must add it to the refinement web
part. Because this is a setting of the web part on a particular search results page, it will not be something
that you will normally do programmatically (not that it can’t be done programmatically, it’s just not
common).
The Refinement web part will present you with a list of all available managed properties that you can use
as a refiner. You simply select the refiner you want to add, click Add, and then configure the refiner. As
previously mentioned, each refiner has a series of properties that you must configure. All of these
properties are conveniently displayed in the refinement web part’s configuration dialog.
Demonstration: Creating and Configuring Refiners

The instructor will now demonstrate how managed properties are configured for use in refinement.
Demonstration Steps
3. On the Windows Start page, type SharePoint, and then click SharePoint 2013 Central
Administration.
6. In the quick launch section, under Queries and Results, click Search Schema.
7. In the Managed property box, type Author, and then press Enter.
8. Click the DisplayAuthor managed property.
9. Note the Refinable property is set to Yes - active; this allows the property to be used as a refiner.
10. Open a new browser tab, in the address bar, type http://search.contoso.com, and then press Enter.
11. On the Search home page, in the text box, type SharePoint, and then press Enter.
12. On the results page, click Settings, and then click Edit page.
13. In the Navigation Zone section, click the Refinement Web Part Menu drop-down arrow, and then
click Edit Web Part.
14. In the Refinement section, click the Choose Refiners button.

15. In the Refinement configuration for ‘Refinement’ dialog box, there is a list of all available
managed properties for use as a refiner. You should also see the default set of refiners, including the
DisplayAuthor managed property.
16. In the Selected refiners list, click DisplayAuthor, and notice how the configuration area changes.
17. In the Display name box, type Author, and then click OK.
Content Search Web Part

Your users should not be forced to go to your
enterprise search center to find things. You can
easily help them get exposure to things that may
interest them based on where they are in the farm.
In doing this, you need to do mini-searches that
display relevant content based on the page, the list,
the site, or any other number of context-sensitive
areas. This can be accomplished by using the
Content Search Web Part (CSWP).
The CSWP is a new web part introduced in

SharePoint 2013. It is a much-needed improvement
over the Content Query Web Part (CQWP), which
was limited to searching only within a site collection. In comparison, the CSWP can search across the
entire search service application.
The power of the CSWP comes in its configuration abilities. Similar to the search results web part and the
result sources, you can use the Query Builder to target specific content that you would like to display in
the web part, and therefore on a web page. In addition to targeting specific content, you can also utilize
special display templates to display the content. The display templates that show by default are:
 Diagnostic
 Large picture
 Picture on left, 3 lines on right
 Picture on top, 3 lines on bottom
 Recommended items: Picture on left, 3 lines on right
 Two lines
 Video
You can add your own custom display templates for use in the CSWP. These are slightly different from the
display templates used for search results. When you select a display template, the editing dialog will
change. For example, when you select the Diagnostic display template, you will see that you have the
option to add up to 10 managed properties for output. This is helpful when you want to see what
properties a specific index item has. By contrast, the Picture on left, 3 lines on right display template
this only lets you select three managed properties to display.
In addition to pulling results from a locally configured query, you can also have the Content Search web
part fed results from another search web part (such as the search results web part). This enables you to
customize a search results web page to have other results display in a very specific manner (such as a
Twitter or Bing feed).
Lab A: Configuring Result Types and Display Templates

Scenario
Contoso users have found that their search results typically include many tasks. Team leaders have asked
whether these search results can be displayed differently to help users distinguish between tasks and
other content when they perform a search. To meet these requirements, you will configure a result type
for the Task content type. You will then configure display templates to customize how matching results
are displayed.
Objectives
 Create and configure a custom result type.
 Customize an item display template.
 Customize a hover panel display template.
Lab Setup
Exercise 1: Configuring and Testing a Result Type

Scenario
Contoso users would like to be able to distinguish Task results from other items in the search results. You
have decided to create a new result type and a corresponding display template for this Task result type.

1. Create and Test a Custom Result Type
 Task 1: Create and Test a Custom Result Type

password Pa$$w0rd.
3. Open the site at http://search.contoso.com in SharePoint Designer 2013.
4. Browse to the search display templates in the master page gallery.
5. Make a copy of the Item_Default.html display template in the same folder, and name the copy
Item_Tasks.html.
6. Open the Item_Task.html file in editing mode.
7. Change the title of the display template to Task Item, then save the file.
8. Open Internet Explorer and browse to http://search.contoso.com.

9. In the browser user interface, browse to the search display templates in the master page gallery.
10. Locate the Item_Tasks.html file. Notice that SharePoint has automatically created an associated
JavaScript file named Item_Tasks.js.
11. Edit the properties of the Item_Tasks.html item, and select all available target control types.
12. At the site collection scope, create a new result type named Tasks.
13. Configure the result type conditions to match items with a content type of Task.
14. Configure the result type actions to use the Item Task display template, and then save your changes.
15. On the Search site home page, run a search for ContentType:Task.
16. SharePoint will display five results. Notice that there is no visual difference between the new display
template and the standard (out-of-the-box) display template.
Note: You will customize the Item Task display template in the next exercise.
Results: After completing this lab, you should have created a new result type and a new display template.
Exercise 2: Customizing an Item Display Template

Scenario
You have been asked to build a display template that shows the Assigned To column property in the
search results if the item is a task.
1. Customize an Item Display Template
 Task 1: Customize an Item Display Template

1. Switch to SharePoint Designer 2013.
2. In the Item_Tasks.html file, locate the following code:
3. Replace it with the following code:
<h3>
<img src="/_layouts/images/icon_tasklist.gif" style="padding-right:5px;border:0px"/>
Title: <a href='_#=ctx.CurrentItem.Path=#_'>_#=ctx.CurrentItem.Title=#_</a><br />
Assigned To: _#=ctx.CurrentItem.AssignedTo=#_<br />
</h3>
Note: You may notice that SharePoint Designer displays some schema errors in the HTML
file. You can safely ignore these errors.
4. Save your work, and then switch to Internet Explorer.

5. On the Search site home page, run a search for Project. Notice that the results use your new display
template.
Results: After completing this exercise, you should have customized an item display template.
Exercise 3: Customizing a Hover Panel Display Template

Scenario
Users are happy with the new Task result type and the display template, but when they hover over the
result, they would like to see more information in the callout. They have asked you to add some
information to the hover panel.
1. Create and Customize a Hover Panel Display Template
 Task 1: Create and Customize a Hover Panel Display Template

2. Browse to the search display templates in the master page gallery.
3. Make a copy of the Item_Default_HoverPanel.html display template in the same folder, and name
the copy Item_Tasks_HoverPanel.html.
4. Open the Item_Tasks.html file in editing mode.
5. Locate the line of code that sets a variable named hoverUrl to the URL of the
Item_Default_HoverPanel.html file. Amend this code to specify the URL of the
Item_Tasks_HoverPanel.html file.
6. Save your work, and then close the Items_Tasks.html file.
7. Open the Items_Tasks_HoverPanel.html file in edit mode.
8. In the Item_Tasks_HoverPanel.html file, locate the following code:
_#= ctx.RenderBody(ctx) =#_
9. On a new line, add the following code:
<br/>
Modified: _#=ctx.CurrentItem.LastModifiedTime =#_
10. Save your work, and then switch to Internet Explorer.
11. On the Search site home page, run a search for Project.
12. Move the mouse over one of the results. Notice that the hover panel appears, showing the Modify
date.
13. Close Internet Explorer, and then close SharePoint Designer 2013.
Results: After completing this exercise, you should have created a hover panel display template for your
custom Task result type.
Lesson 3
Customizing Content Processing
In this lesson you will learn how to supplement the content processing to meet your organization’s search
needs. This will involve configuring search to handle both structured and unstructured data. You will also
learn how to supplement SharePoint search logic with your own business logic for enhancing managed
property values.
Lesson Objectives
 Create and configure entity extractors
 Describe company name extractors
 Create and deploy a thesaurus
 Configure Query Spelling inclusions and exclusions

 Create and Configure a Content Enrichment Service
Entity Extractors
Many organizations have terabytes of data, much of
it unstructured. Unstructured simply means that it
has no metadata wrapped around it that can be
easily abstracted via a common algorithm or
process. In these cases, this data can be queried
only based on the text that is abstracted. FAST
Search in SharePoint 2010 introduced a concept
called entity extractors. These extractors are
designed to look for keywords in this unstructured
content and build a structured way of searching for
common content. This feature was moved forward
into SharePoint 2013 search.
There are four types of entity extractors:
 Word Extraction. Case-insensitive dictionary entries matching tokenized content, with a maximum of
five dictionaries.
 Word Part Extraction. Case-insensitive dictionary entries matching un-tokenized content, with a
maximum of five dictionaries.
 Word Exact Extraction. Case-sensitive dictionary entries matching tokenized content, with a maximum
of a single dictionary.
 Word Part Exact Extraction. Case-sensitive dictionary entries matching un-tokenized content, with a
maximum of a single dictionary.
As you can see, you don’t have an unlimited number of extractors like you had in FAST Search. You are
limited to a total of 12 entity extractors.
Configuring Entity Extractors

To configure Entity extractors, you must first create
a text file that contains a comma-delimited set of
values. There are two values. The first value defines
the term the extractor should look for, and the
second value is what the value will be mapped to
for search and refinement.
Adding entity extractors is done via Windows

PowerShell via the Import-
SPEnterpriseSearchCustomExtractionDictionary
cmdlet. It accepts three parameters: Search Service
Application, the path to the extractor file (which
must be a UNC path), and the dictionary name. The
dictionary name is not a very obvious value, so for reference here are its possible values:
 Microsoft.UserDictionaries.EntityExtraction.Custom.Word.[1-5]
 Microsoft.UserDictionaries.EntityExtraction.Custom.WordPart.[1-5]
 Microsoft.UserDictionaries.EntityExtraction.Custom.ExactWord
 Microsoft.UserDictionaries.EntityExtraction.Custom.WordWordPart
Note that the value [1-5] is an integer.
To create a new entity extractor, you should create a new text file on a network share. You then add
content to it in comma separated format.
The following code example shows an entity extraction file:
Entity Extractor Example

Key, Display form
Pinot Noir, Red Wine
Merlot, Red Wine
Shiraz, Red Wine
Chardonnay, White Wine
Pinot Grigio, White Wine
Riesling, White Wine
When you have created the file, you can use Windows PowerShell to import the entity definitions into
SharePoint.
The following code example shows how to import an entity extraction file into SharePoint by using
Windows PowerShell:
Importing an Entity Extraction File

Import-SPEnterpriseSearchCustomExtractionDictionary -SearchApplication $searchApp -

Filename <Path> -DictionaryName Microsoft.UserDictionaries.EntityExtraction.Custom.Word.1
Company Name Extractors

Company names are a special attribute of content
that is very helpful for users to be able to search
and to refine results upon. Because of its
importance, it has been given its own property that
is separate from generic entity extractors.
There is a difference in the way a company name

extractor is set up and the way the generic
extractors are set up. Company name extractors
utilize managed metadata service application. You
can add both exclusion and inclusion names.
Once you have added your included and excluded

values to the term store, you must then tell
SharePoint search where it should look for these values. By default, it will look in the Body and Title
managed properties. If you want it to look in other places, such as a Company managed property, you will
need to check that configuration value when editing the managed property.
Once you have configured the term store and managed properties, a full crawl will be needed to populate
the values. These values can then be used in the refinement web part to assist users in drilling down into
the specific company content they are looking for.
Creating and Deploying a Thesaurus

A thesaurus is a way of helping users find what they
are looking for by supplementing the user’s query
based on synonyms. Commonly this is done for
company-specific acronyms. For example, the
acronym IE is typically tied to the phrase Internet
Explorer. When a user does a search for IE, they
would expect items that have Internet explorer in
them to show up. Unfortunately, that is not the
case. You must deploy a thesaurus to make the
search engine smarter about these types of terms.
Deploying
In previous versions of SharePoint Search, the
thesaurus file was stored on the file system, changes could be made directly against a file, and then you
could simply restart the Search service to apply the changes. In SharePoint 2013, you can no longer
modify the thesaurus in this way. Similar to Entity extractors, you must build and maintain a comma-
separated file that you then deploy via Windows PowerShell. Each time you want to make a change to the
thesaurus, you must update the entire thesaurus file. There is no delta update functionality, nor is there
any means of exporting thesaurus settings.
For each thesaurus entry, you also have the option of specifying the language that that entry will target.
Reference Links: For more information on the supported languages, see Create and
deploy a thesaurus in SharePoint Server 2013 at http://go.microsoft.com/fwlink/?LinkId=321936
Encoding
If your entries contain language-specific special characters, you will need to make sure that the file is UTF-
8 encoded.
Case Sensitivity
Thesaurus entries are not case sensitive when being applied to queries.
Query Processing
Once you have created and deployed your thesaurus file, the search engine will process a query and look
for any query terms that match a thesaurus key. If there are any matches, the query is expanded with the
synonym(s) for that key and the search results will contain results for the original query term as well as for
the synonym. You should be aware that synonyms are only one way, so if you want IE to mean Internet
Explorer and Internet Explorer to mean IE, you would need two entries in the thesaurus file.
Replacements
Another change from the way earlier versions of SharePoint Search operated was that it enabled you to
specify replacements. With a replacement, a word would be substituted with another word in a search
query. In SharePoint 2013, all entries in the thesaurus are expansions, and the original term is not
removed from the query. The original query term is always evaluated, and you cannot remove synonyms
or words directly from the index.
Diacritical Marks
Lastly, the thesaurus no longer supports the option to specify whether diacritical marks such as accents
should be ignored or should be applied by the search system when expanding a query with terms from
the thesaurus. By default, diacritical marks are always respected when matching query terms with terms in
the thesaurus
Adding Query Spelling Corrections

As anyone that browses the Internet knows, when
submitting search queries it is inevitable that at
some point you will mistype a search query. When
that happens, most users have become accustomed
to the search engine fixing your mistake and
correctly giving you what you were looking for. The
same mistyping of queries can occur in SharePoint,
both implicitly and explicitly, by a user. When this
happens, you must teach SharePoint how to handle
the situation.
Fixing a user’s query is called Query Spell

Corrections. You can have both included and
excluded terms for spelling corrections. For SharePoint 2013, Query Spell corrections are implemented in
Managed Metadata via a special term set. You can add both inclusion and exclusion terms to the term set.
Note: In most cases you will be adding query spelling exclusions. This is because your
company may have acronyms and product names that deviate from dictionary-based words that
SharePoint will mistake for a spelling error.
Understanding Content Enrichment Web Services

In SharePoint 2013, you can customize content
processing for search items by deploying a content
enrichment web service. A content enrichment web
service is a custom, external Windows
Communication Foundation (WCF) service that
implements the IContentEnrichmentService
interface. When you register a content enrichment
web service with SharePoint, the search service will
call the web service as part of the content
processing phase, which takes place between
crawling and indexing.
A content enrichment web service enables you to

edit the managed properties associated with crawled items before the items are indexed. When you
create and configure a content enrichment web service, you specify:
 Input managed properties that you want to send to the web service.
 Output managed properties that you want to get back from the web service.
You can associate trigger conditions with the content enrichment web service, based on the value of
specified managed properties in the crawled item. For example, you might configure search to call the
content enrichment web service only if the Title managed property contains the text Contoso.
You can only associate one content enrichment web service with any given search service application.
For more information on content enrichment web services, see:

Custom content processing with the Content Enrichment web service callout
Creating a Content Enrichment Service

In order to create a Content Enrichment Service,
you must open Visual Studio and create a new WCF
Service application. This application will then inherit
from a specific interface called
IContentProcessingEnrichmentService. This
interface has one method called ProcessItem. Both
the interface and its corresponding method are
defined in the
Microsoft.Office.Server.Search.ContentProcessin
gEnrichment.dll, which resides in the C:\Program
Files\Microsoft Office
Servers\15.0\Search\Applications\External
directory. This assembly must be added as a reference to your WCF project.
The ProcessItem method has one parameter of type Item. Item has a property called ItemProperties,
which will contain all the requested managed properties that you requested. It is your job to loop through
the various managed properties and do any processing that needs to occur. The ProcessItem method
also has a return type of ProcessedItem. Once the processing is complete, you can add any new or
modified properties to the return back into the ItemProperties property of the ProcessedItem.
It is important that you make the code as efficient as possible. Even though the search engine is multi-
threaded, you are still introducing a lot of latency into the item processing by making the WCF call. You
should take every precaution when building the service. This includes best practices like caching results for
future use.
The following code example shows an implementation of the ProcessItem method:
Implementing the ProcessItem Method

public ProcessedItem ProcessItem(Item item)
{
processedItemHolder.ErrorCode = 0;
processedItemHolder.ItemProperties.Clear();
try
{
// Iterate over each property received
foreach (var property in item.ItemProperties)
{
if (property.Name.Equals(FileNameProperty, StringComparison.Ordinal))
{
var filename = property as Property<string>;
if (filename == null)
{
// Update error code and return.
processedItemHolder.ErrorCode = UnexpectedType;
return processedItemHolder;
}
if (!string.IsNullOrEmpty(filename.Value))
{
var fullFilePath = string.Join(char.ToString(Path.DirectorySeparatorChar),
TempDirectory, filename.Value);
if (item.RawData != null)
{
var outputFile = File.Create(fullFilePath);
using (var writer = new BinaryWriter(outputFile))
{
writer.Write(item.RawData);
}
}
}
}
}
var custom = new Property<string>();

custom.Name = "Address";
custom.Value = "1 Microsoft Way, Redmond, WA";
processedItemHolder.ItemProperties.Add(custom);
}
catch (Exception)
{
processedItemHolder.ErrorCode = UnexpectedError;
}
return processedItemHolder;
}
Configuring Content Enrichment Service

Once you have built your Content Enrichment
Service, you must register it with the SharePoint
Search Service Application. This is done via
Windows PowerShell and has several configuration
parameters that you can set.
The first step to configure your service is to get an

instance of the Search Service Application that you
want to configure. This is done via the Get-
SPEnterpriseSearchServiceApplication cmdlet.
Second, you must create a new Content Enrichment
Configuration by using the New-
SPEnterpriseSearchContentEnrichmentConfigur
ation cmdlet. The object generated from this call has several properties that can be assigned. These
include:
 Endpoint. Defines where the WCF service resides on the network.

 InputProperties. The managed properties you want search to send.
 OutputProperties. The managed properties that your service will return.
 SendRawData. If the item is a file, this will be the actual binary of the file.
 DebugMode. This will send all the managed properties of an item.
 MaxRawDataSize. Some files can be very large, so you should limit the size of the data you send on
each call to the WCF service so that you don’t saturate the network.
 Trigger. A search query that tells the search engine which items should be sent to the WCF service.
It is important to note that the SendRawData and DebugMode properties should only be used in a
development environment. They can cause the entire crawl process performance to drop by several
multiples (from days to weeks).
It is also important to realize that you won’t need to process every single item that exists in the index.
Your code will target only certain types of content. Therefore, there is no need for the search engine to
pass you the properties and wait for empty logic to execute. In these cases, you will use a trigger
expression that will limit the items that the search engine sends to your service. This is a best practice, and
you should always have a trigger expression.
You can remove a connection to a Content Enrichment service by running the Remove-
SPEnterpriseSearchContentEnrichmentConfiguration cmdlet.
The following code example shows how to configure a content enrichment service by using Windows
PowerShell:
Configuring a Content Enrichment Service

$ssa = Get-SPEnterpriseSearchServiceApplication
$config = New-SPEnterpriseSearchContentEnrichmentConfiguration
$config.Endpoint = "http://WCF_URL/ContentEnrichmentService.svc"
$config.InputProperties = "Author", "Filename", "Address", "Latitude", "Longitude"
$config.OutputProperties = "Author", "Filename", "Address", "Latitude", "Longitude"
$config.SendRawData = $True
$config.DebugMode = $True
$config.MaxRawDataSize = 8192
$config.Trigger = ‘NOT IsNull(Address)’
Set-SPEnterpriseSearchContentEnrichmentConfiguration –SearchApplication $ssa -

ContentEnrichmentConfiguration $config
Discussion: Content Enrichment Service

In what cases might you want to implement a
Content Enrichment Service?
Lab B: Configuring Entity Extraction

Scenario
As part of a rewards program, Contoso has published a catalog of MP3 players and related products. The
catalog users have requested the ability to sort and filter products by memory size. To implement this
request, you will create and deploy an entity extractor and then configure a refinement web part on the
search results page.
Objectives
 Create and deploy an entity extraction dictionary file.
 Configure a managed property for entity extraction.

 Configure a refinement web part to enable users to filter search results by the extracted entities.
Lab Setup
Exercise 1: Creating and Deploying an Entity Extractor

Scenario
In this exercise, you will create an entity extraction dictionary file in Notepad, and import the file into
SharePoint by using Windows PowerShell. You will then configure a managed property to support entity
extraction. Finally, you will configure the Refinement Web Part on the search results page to use your
entity extractor.
1. Create and Deploy an Entity Extractor Input File
2. Configure a Managed Property for Entity Extraction
3. Configure Refinement Based on Extracted Entities
 Task 1: Create and Deploy an Entity Extractor Input File

password Pa$$w0rd.
3. In the E:\Labfiles\Starter folder, create a new folder named EntityExtractor. Grant the
CONTOSO\SPFarm account read permissions on the folder.
4. In the EntityExtractor folder, create a new text file named Memory.txt.
5. Add the following content to the file:

Key, Display form

512MB, 512MB
1024MB, 1GB
1GB, 1GB
2GB, 2GB
4GB, 4GB
8GB, 8GB
16GB, 16GB
6. Use Windows PowerShell to deploy the Memory.txt file to SharePoint as a custom extraction
dictionary.
Note: When you import the dictionary file, specify the filename in UNC format as
\\London\EntityExtractor\Memory.txt. Specify the dictionary name as
Microsoft.UserDictionaries.EntityExtraction.Custom.Word.1.
 Task 2: Configure a Managed Property for Entity Extraction

1. Open the Central Administration website and browse to the Search Administration page for the
Contoso Search service application.
2. Browse to the search schema and edit the managed property named Title.
3. In the Custom entity extraction section, select Word Extraction – Custom1, and then save your
changes.
4. Edit the managed property named Description.

5. In the Custom entity extraction section, select Word Extraction – Custom1, and then save your
changes.
6. Run a full search crawl. Wait for the crawl to complete before you continue.
 Task 3: Configure Refinement Based on Extracted Entities

1. In Internet Explorer, browse to http://search.contoso.com.
2. Run a search for mp3 player, and verify that several results appear.
3. On the search results page, open the settings pane for the Refinement web part.
4. Add the WordCustomRefiner1 refiner to the Refinement web part. Set the display name for the
refiner to Memory.
5. Apply your changes, and then save and check in the page.
6. Search for mp3 player again.
7. In the refiners on the left of the page, click 8GB. Notice that the search results are filtered to show
only those items that include 8GB in the title or description.
Results: After completing this exercise, you should have created, deployed, and tested a custom entity
extractor.
Question: How many different types of entity extractors are available?
Question: What must you do after registering the entity extractor file?

In this module you were exposed to many of the new enhancements that enable developers and search
administrators to customize the search experience for users. You now have the skills to:
 Create custom result sources and use them in custom search result pages.
 Find, modify and create new display templates.
 Create new result types with specific display templates.
 Create hover panels for search results.
Review Question(s)
Test Your Knowledge

Question
What web part do you configure to show data from a specific result source on a typical search
result page?
Search Results
Content Query
Refinement
Search Textbox
Search Navigation
Test Your Knowledge

Question
Which of the following is implemented by using managed metadata?
Entity extractors
Thesaurus
Content Enrichment Service
Display Template
Company Name Extractor

Statement Answer
True or False: You can create result types at

the Service Application level.
Statement Answer
True or False: Setting the refinable property

will make the refinement web part display the
refiner in search results.
5-1
Module 5
Implementing Enterprise Content Management
Contents:
Module Overview 5-1
Lesson 1: Working with eDiscovery 5-2
Lesson 2: Working with Content Management 5-11
Lesson 3: Automating Records Management 5-18
Lab: Implementing Content Management Functionality 5-25
Module Overview
If you use Microsoft® SharePoint® to store documents in a large or complex organization, you may have
a number of functional and legal requirements to satisfy. For example, in the event of litigation, you must
be able to locate all documents that relate to the case, ensure that they cannot be changed, and export
them to your lawyers. You may want to ensure that documents are kept for a fixed period, or manage a
group of documents as a single entity. Other scenarios involve automating the movement of complete or
expired documents to an archive. SharePoint Server 2013 includes a range of facilities to satisfy these
requirements. In this module, you will see how to work with these document management features in
code.
Objectives
 Use SharePoint eDiscovery functionality in custom applications.
 Programmatically create and manage information management policies and document sets.
 Manage and customize SharePoint records management functionality.

5-2 Implementing Enterprise Content Management
Lesson 1
Working with eDiscovery
Electronic Discovery, or eDiscovery, is the process of identifying and delivering electronic information for
use as evidence. This is usually for legal purposes, when the content identified relates to a legal case, but it
may also be for internal investigations within your organization. When a case arises, you must be able to
locate all relevant content quickly, confirm that users cannot tamper with the located content, and export
the content to stakeholders such as attorneys and investigators. All of these requirements can be satisfied
by using eDiscovery Centers in SharePoint Server 2013.
Lesson Objectives
 Describe how to locate, hold, and export content for legal and other purposes.
 Describe the eDiscovery Center and the objects and facilities a Discovery Center can include.
 Choose classes in the eDiscovery APIs for programmatic tasks.
 Create eDiscovery cases and sets by writing code in C#.
 Apply a hold to content in a set.
 Query and export content from an eDiscovery Center.
eDiscovery Overview
In many organizations, SharePoint is the primary
content store. When a legal case arises, such as a
disputed contract or a libel, it is likely that one or
more documents that relate to the case are in the
SharePoint content database. If the documents are
not in the content database, they may be in another
location that is indexed by the SharePoint Search
service, such as a file share. In modern organizations
there may be no hard copies of these documents.
When cases arise, you must complete three tasks:
1. Locate all the documents and other items that

relate to the case.
2. Control these located documents so that the current version cannot be tampered with by anyone
involved in the case.
3. Export these documents in a form that can be used by all stakeholders to investigate what happened.
In SharePoint 2013, you can use an eDiscovery Center to complete these tasks.
eDiscovery Infrastructure
An eDiscovery Center is a site collection created by using the eDiscovery Center template. If you expect to
use eDiscovery in your organization, you should plan for and create an eDiscovery Center site collection
so that it is ready for investigators to use. When a case arises, site collection administrators can choose the
users who can create cases. Each eDiscovery case is a sub-site in the eDiscovery site collection, created by
using the eDiscovery Case site template.
Once you have created an eDiscovery Case you can search for content that relates to the case. eDiscovery
uses the SharePoint Search Service to locate content. Therefore, the limits of an eDiscovery search match
the limits of the Search Service index. Search administrators must confirm that all the locations where
documents are stored are included as content sources in the Search configuration. These locations can
include:
 SharePoint Content. Administrators can configure a single Search service application to index not only
the content in the local SharePoint farm, but also other SharePoint farms on the network.
 File Shares. Documents that have not been saved to SharePoint, but are stored in a Server Message
Block (SMB) file share can be indexed.
 Business Connectivity Services Connections. Any location to which SharePoint can make a BCS
connection can be indexed.
 Exchange Server. SharePoint can index Microsoft Exchange Server items in mailboxes and public
folders. In addition, if you archive Microsoft Lync® 2013 conversations in Exchange Server, these
conversations can be included in the SharePoint Search index, and therefore you can locate them
through eDiscovery.
Integrating with Exchange

In order to discover Exchange content in a SharePoint 2013 eDiscovery Center, you must be running
Exchange Server 2013. If this is the case, an administrator must complete the following configuration
tasks:
 Install the Exchange Web Services Managed API. This must be done on every SharePoint web front-
end server.
 Configure a server-to-server trust relationship. This trust relationship enables SharePoint to

authenticate with Exchange Server.
 Add authorized users to the Discovery Management role. This role membership enables users to
discover potentially sensitive content in private mailboxes. You must take care to who you assign this
permission because it can enable access to private information.
To download the Exchange Web Services Managed API, follow this link:
Exchange Web Services Managed API

For more information about configuring server-to-server trust relationships, follow this link:
Configure server-to-server authentication between SharePoint 2013 and Exchange Server

2013
eDiscovery Processes
When a case arises, users create a new eDiscovery
Case site within the eDiscovery Center site
collection. From within the new case, users can
perform all the operations required to locate,
control, and export the content that relates to the
case. This includes the following operations:
eDiscovery Sets and Holds

Sets and holds are used to control content in order
to protect it from tampering. This is essential when
documents are used as evidence.
When a case has been created, you must locate

content by creating eDiscovery sets. For each set, you can specify multiple content sources. Content
sources can include:
 Exchange Mailboxes
 SharePoint sites
 File shares
Once you have defined the content sources for a set, you can also define filters to focus the set on
relevant documents. The filters can include:
 A date range
 A document author or email message sender
 An Exchange domain
By configuring sets in this way, you specify the content that the case relates to. For example, if the court
has informed you that the case concerns an email from a particular user on a given date, you can add a
specific mailbox as a content source and filters for the email sender and a narrow date range.
Having defined a content set, you can enable an in-place hold for the set. When a hold is applied, the
current version of the document is preserved as evidence. SharePoint creates a preservation hold library in
each SharePoint site included in the set. If a user modifies a document, a copy is placed in this folder. In
this way, users can continue to work on documents, but the version that is current when the hold is
imposed is protected. This preserved version is the one that is included in exports.
eDiscovery Queries and Exports

The eDiscovery sets you define in a case fix the content sources that are relevant to the case and can
apply a hold. Once you have defined sets, you can run queries to identify documents and other items that
are relevant to a particular aspect of the case. Having identified this content, you can export the content.
An export creates files in an industry-standard format called the Electronic Data Reference Model (EDRM).
You can pass this export to any stakeholder in the case.
Objects in the eDiscovery API

SharePoint 2013 includes a range of API classes that
enable you to work with eDiscovery in server-side
code. These are stored in two separate namespaces:
The Microsoft.Office.Server.Discovery
Namespace
This namespace includes that following classes:
 Case. This class represents an eDiscovery case.

Because a case is a SharePoint site in the
eDiscovery Center site collection, you can
access items by using the SPWeb class.
However, the Case class, includes specialist
methods and properties such as CreateExport and Sources.
 SourceGroup. This class represents an eDiscovery set. You can use its methods and properties to
manage content sources and filters.
 Source. This class represents a content source within an eDiscovery set.
 SavedSearch. This class represents an eDiscovery query. You can use this class’s properties to set filters
and content sources for the query and to determine the total size of the query.
 Export. This class represents an export for the results of an eDiscovery query. You can use the
properties of this class to check the status of the export and access the download link.
The Microsoft.Office.RecordsManagement.Preservation Namespace

This namespace has two classes that represent eDiscovery holds:
 HoldInfo. You can use this class to find out about a hold. For example, you can determine the case
that the hold relates to and the filters that are used to target the hold to relevant content.
 HoldSettings. You can use this class to manage holds. For example, you can add content on a
SharePoint site to a hold by using the HoldSettings.AddToHold() method.
In the following topics, you will see code samples that demonstrate how to use these classes.
Creating Cases
In SharePoint, an eDiscovery case is a sub-site
within an eDiscovery Center site collection. To
create a new case, you must therefore create a new
SPWeb object based on the correct site template.
The eDiscovery Case site template has the name
"EDISC#1". Once you have created the SPWeb
object, you can pass it to the Case class constructor
to access eDiscovery methods such as CloseCase()
and CreateExport().
The following sample code creates a new SharePoint site based on the eDiscovery Case site template. The
code also demonstrates how to set the case to close after one month:
Creating an eDiscovery Case

using (SPSite discoveryCenter = new SPSite("http://ediscovery.contoso.com"))
{
//Create a new SPWeb based on the eDiscovery Case site template
SPWeb discoveryWeb = discoveryCenter.AllWebs.Add("Cases/NewCase", "An Example Case",
"This site is to demonstrate creating cases", 1033, "EDISC#1", false, false);
//Get the Case object

Case discoveryCase = new Case (discoveryWeb);
//Set the case to close after 1 month

TimeSpan caseDuration = new TimeSpan(31, 0, 0, 0);
DateTime closingDate = DateTime.Now.Add(caseDuration);
discoveryCase.CloseCase(closingDate);
discoveryWeb.Dispose();
}
Creating Sets and Applying Holds

When you work with an eDiscovery case, you obtain
the corresponding SPWeb object and pass that to
the Case constructor to access specialized
eDiscovery methods. This is because a case is a
SharePoint site. eDiscovery sets and sources are
items in SharePoint lists. Therefore, when you work
with eDiscovery sets and sources, you obtain the
corresponding SPListItem objects and pass them to
the SourceGroup and Source constructors to
access specialized eDiscovery methods.
Creating a Set and Adding Content

Sources
The eDiscovery Case site template creates a list called "eDiscovery Sets". When you create a set, add an
item to this list. Similarly, to create a source, create an item in the "Sources" list.
The following code sample creates a set and a source within the set:
Creating a Set and a Source

using (SPWeb discoveryWeb = new SPWeb("http://ediscovery.contoso.com/cases/newcase"))
{
//Get the eDiscovery case
Case discoveryCase = new Case(discoveryWeb);
//Get the list of sets and sources

SPList discoverySetsList = discoveryWeb.Lists["eDiscovery Sets"];
SPList discoverySourcesList = discoveryWeb.Lists["Sources"];
//Create a new list item for the set

SPListItem setItem = discoverySetsList.Items.Add();
setItem["SPBuiltInFieldId.Title"] = "Example eDiscovery Set";
setItem.Update();
//Get the corresponding SourceGroup for the set

SourceGroup set = new SourceGroup(setItem);
//Create a new list item for the source

SPListItem sourceItem = discoverySourcesList.Items.Add();
sourceItem["SPBuiltInFieldId.Title"] = "Example Source";
sourceItem.Update();
//Get the corresponding Source object

Source source = new Source(sourceItem);
//Get the web site for the location

using (SPWeb sourceWeb = new SPWeb("http://dev.contoso.com "))
{
Guid sourceWebId = sourceWeb.ID
//Set the source ID

source.WebId = sourceWebId;
source.Update();
}
//Add the source to the set

set.AddSource(source);
set.Update();
}
Applying Holds
When the user selects Enable in place hold in an eDiscovery set, holds are created and applied for each
SharePoint site and Exchange mailbox in the discovery set. To perform this task in code, you must
therefore loop through all the sources in the eDiscovery set. If these sources are SharePoint sites or
Exchange mailboxes, you can use the HoldSettings.AddToHold() method to apply the hold.
The following code illustrates how to apply holds for all the SharePoint sources in a set:
Applying Holds Programmatically

using (SPSite discoveryCenter = new SPSite("http://ediscovery.contoso.com")
{
using (SPWeb discoveryWeb = discoveryCenter.AllWebs["An Example Case"])

{
//Get the eDiscovery case

//Get the list of sets and sources

SPList discoverySetsList = discoveryWeb.Lists["eDiscovery Sets"];
//Get the list item for the set

SPListItem setItem = discoverySetsList.Items["Example eDiscovery Set"]
//Get the corresponding SourceGroup for the set

SourceGroup set = new SourceGroup(setItem);
//Loop through all the sources in the set

foreach(Source currentSource in set.Sources_Client)
{
//Make sure this is a SharePoint site
if (currentSource.SourceType == SourceType.SharePoint15)
{
//Find out about the site collection
SPSite siteToHold = new SPSite(currentSource.SiteID);
//Create a Hold Settings object for the site collection

HoldSettings siteHoldSettings = new HoldSettings(siteToHold);
//Find out about the site collection

SPWeb webToHold = siteToHold.AllWebs[currentSource.WebID];
//Create a new hold

HoldInfo currentHoldInfo = new HoldInfo();
string errorMessage;
Guid holdId = Guid.NewGuid();
siteHoldSettings.Add(discoveryCase.ID, holdId, webToHold.ServerRelativeUrl,
set.Query, 1033,
currentHoldInfo, errorMessage);
//Save your new hold

siteHoldSettings.Update();
//Remember to dispose of the SPSite and SPWeb

webToHold.Dispose();
siteToHold.Dispose();
}
}
}
}
Querying and Exporting Content

When you create an eDiscovery case, you add
multiple content sources, such as SharePoint sites
and Exchange mailboxes. These sources define all
the possible locations that might hold evidence that
is relevant to the case. Before you can export
content, you must run a query against one or more
sources or sets. Having run a query, you can create
an export that enables a user to download the
EDRM files with all the items and documents that
bear upon the case.
Creating a Query
In the Microsoft.Office.Server.Discovery
namespace, an eDiscovery query is represented by the SavedSearch class. You can create a SavedSearch
by creating a new SPListItem in the Queries list. You can use the SavedSearch() constructor to access
specialized eDiscovery methods. You must set query properties and save them by calling the Update()
method.
You must bind a SavedSearch to a content source or set. To do this use the Source and SourceGroups
properties on the corresponding list item. Because these are multi-valued lookup values, you must create
a SPFieldLookupValueCollection and add values to it to save sources or sets.
Note: Do not confuse eDiscovery queries, represented by the SavedSearch class, with the
SourceGroup.Query property, which represents a filter on an eDiscovery set.
The following code shows how to create a SavedSearch object in an eDiscovery case:
Creating an eDiscovery Query

{

{
//Get the list of saved searches

SPList savedSearchesList = discoveryWeb.Lists["Queries"];
//Create the saved search item

SPListItem savedSearchItem = savedSearchesList.Items.Add();
setItem["SPBuiltInFieldId.Title"] = "Example eDiscovery Query";
//Find out about the source

SPListItem source = discoveryWeb.Lists["Sources"].Items["Example Source "]
//Set the content source lookup field

SPFieldLookupValueCollection lookupValues = new SPFieldLookupValueCollection();
SPFieldLookupValue sourceValue = new SPFieldLookupValue(source.ID, source.Title)
lookupValues.Add(sourceValue);
savedSearchItem["Sources"] = lookupValue.ToString();
savedSearchItem.Update();
//Now get the SavedSearch object

SavedSearch savedSearch = new SavedSearch(savedSearchItem)
//Set the query

savedSearch.Query = "SharePoint";
savedSearch.Update();
Creating Exports
To create an export in the Exports list you can use the Case.CreateExport() method. This method can
take Boolean values that indicate whether to include all versions of a document, whether to include
encrypted files, and whether to duplicate mailbox content if the same message appears in multiple
mailboxes.
The following code sample shows how to export content from a query programmatically:
Creating Exports Programmatically

{

{
//Get the list of exports

SPList exportsList = discoveryWeb.Lists["Exports"];
//Create the export item

SPListItem exportItem = exportsList.Items.Add();
exportItem["SPBuiltInFieldId.Title"] = "Example eDiscovery Export";
//Find out about the query

SPListItem queryItem = discoveryWeb.Lists["Queries"].Items["Example Query"]
//Get the Case object

Export newExport = discoveryCase.CreateExport();
//Set the queries lookup field

SPFieldLookupValueCollection lookupValues = new SPFieldLookupValueCollection();
SPFieldLookupValue savedSearchValue = new SPFieldLookupValue(queryItem.ID,
queryItem.Title)
lookupValues.Add(savedSearchValue);
exportItem["Queries"] = lookupValues.ToString();
exportItem.Update();
}
}
Lesson 2
Working with Content Management
When you have a large quantity of content of different types in your SharePoint content database,
administration can become onerous. For example, suppose your organization has a new product. Authors
create 30 documents about the product, including posters, instruction manuals, sales materials, and more.
Six months after the product is released you want to archive all these documents. Five years after release,
you want to be sure that all of these documents are deleted. Meanwhile, many other products are
created, each of which has a similar body of documentation. By using a document set, you can reduce this
administrative workload because you take actions on all the product's documents in a single step. By
using information management policies, you can automate the deletion of the documents. In this lesson,
you will see how to code document sets and information management policies.
Lesson Objectives
 Describe how information management policy enables administrators to control content.
 Describe the components of an information management policy.

 Create and export an information management policy.
 Write code to import a policy and associate it with a content type.
 Describe how document sets are used to group documents for management purposes.
 Write code to create a document set.
Overview of Information Management Policy

In SharePoint Server 2013, you can create an
information management policy for each content
type. An information management policy is a set of
rules that set properties for a content type. By
setting these rules on a centralized policy object,
you help administrators to govern documents
without having to manage each document
individually.
Policy Features
Four policy features are included in SharePoint
Server 2013. Administrators can define one or more
of these features in each information management
policy:
 Retention. The retention policy feature enables you to define stages in the lifecycle of each document.
At the end of each stage, you can define an action that will be taken on each document. For example,
your policy could delete all earlier versions of a document after one year, and then declare the
document as a record after two years.
 Auditing. The auditing policy feature enables you to specify which actions on a document are
recorded in the SharePoint audit logs. Using these logs, you can verify that sensitive information is
accessed only by authorized users. In the event of a security breach, the audit logs may help you to
determine the user who accessed the sensitive data. You can audit operations such as changes, reads,
check-ins, check-outs, permission changes and deletions.
 Labeling. A label is a searchable text area that SharePoint can generate by concatenating values from
the other fields of an item. For example, a label for a contact item may include the contact name and
address fields. Labels are useful when documents are printed.
 Barcode. The barcode policy feature can generate a barcode for a document that is compliant with
the common Code 39 standard. By inserting the barcode image in the document you can enable bar
code readers to identify the document.
Note: Take care not to confuse information management policies, which govern content,
with site policies, which govern sites. Site policies help site collection administrators prevent the
proliferation of sites. They cannot be used to govern individual documents or items.
Configuring Audit Logs

The auditing policy feature enables you to set actions that will be stored in the audit logs. However,
auditing will only occur if SharePoint administrators have completed the following tasks:
 Configure the Secure Store Service Application. Auditing requires the Secure Store Service Application
to be running in the SharePoint farm. Administrators can create this service application in Central
Administration or PowerShell.
 Start the Secure Store Service. After configuring a Secure Store service application, administrators must
start the Secure Store Service on at least one SharePoint server in the farm.
Once audit logging has been configured, you can view the audit logs at the site collection level:
1. Browse to the top-level site in the site collection.
2. Click the Settings icon, and then click Site Settings.
3. Under Site Collection Administration, click Audit Log Reports.
4. Click the report of interest. Available reports include Content viewing, Content modifications, and
Deletions.
Components of Policies
A policy consists of one or more items. Each item
refers to one of the four policy features: retention,
auditing, barcodes and labeling. Some features
make use of policy resources to execute actions
such as retention stages.
Policy XML
An information management policy is stored as
XML file with a specific schema in the SharePoint
content store. You can export these XML files and
then import them into other site collections in the
same SharePoint farm. You can also import the XML
files into other SharePoint farms.
Most elements in the policy XML file have the p: prefix. For example, the top-level element is always a
<p:Policy> element.
The Structure of a Policy

Information management policies are managed at the site collection level by site collection
administrators. There is a single collection of policies for each site collection. The collection can contain
any number of information management policies.
Each policy is made up of one to four policy items. A policy item stores the settings for one of the four
policy features: retention, auditing, barcodes, and labeling. You can choose whether to include policy
items for each of the policy features in your policy.
Some policy features make use of resources to execute their actions. For example, the retention feature
can call resources such as DeletePreviousVersions and MoveToRecycleBin when each retention stage
ends.
Demonstration: Creating and Exporting a Policy

 Create an information management policy.

 Add a retention policy item.
 Add an auditing policy item.
 Add a barcode policy item.

 Export a policy and understand the policy XML file.
Demonstration Steps
1. Access the Content Type Policy Templates list for the http://dev.contoso.com site collection.
2. Create a new information management policy. Use the following information:
o Name: Example Policy.
o Administrative Description: This policy is to demonstrate export.

o Policy Statement: This is the policy for legal documents.
3. Enable retention and add a retention stage that deletes all previous versions of documents one year
after creation.
4. Enable auditing for editing items.
5. Enable barcodes and save the policy.
6. Export the policy to Downloads folder, and then open the Export Policy.xml file in Internet
Explorer®.
7. Close Internet Explorer and then close File Explorer.

Programming Policy
Objects that enable developers to work with
information management policy are found in the
Microsoft.Office.RecordsManagement.Informati
onPolicy namespace. You can import and export
policy documents as well as associate a policy with
a content type.
Note: To access the

Microsoft.Office.RecordsManagement.Informati
onPolicy namespace, add a reference to the
Microsoft.Office.Policy extension in Visual Studio.
Importing a Policy
To import a policy XML file into a SharePoint site collection, you must first access the policy catalog for
the site collection. To perform the import, pass the XML file to the static PolicyCollection.Add() method,
along with the site collection.
The easiest way to create a string representation of the XML file is to use XMLDocument class along with
a StringWriter object and an XmlTextWriter object. This requires references to the System.IO and
System.Xml namespaces.
This code example illustrates how to import a policy from a correctly formatted XML file:
Importing a Policy
using (SPSite site = new SPSite("http://intranet.contoso.com"))
{
//Access the policy catalog
PolicyCatalog policyCatalog = new PolicyCatalog(site);
//Get the XML as a string

XmlDocument xmlDoc = new XmlDocument();
xmlDoc.Load("C:\\Policies\\MyPolicy.xml");
StringWriter stringWriter = new StringWriter();
XmlTextWriter xmlTextWriter = new XmlTextWriter(stringWriter);
xmlDoc.WriteTo(xmlTextWriter);
string policyXml = stringWriter.ToString();
//Import the policy

PolicyCollection.Add(site, policyXml);
}
Associating a Policy with a Content Type

Before an information management policy can take effect, you must associate it with a content type. To
do this in code, access the policy from the policy catalog and pass it to the static Policy.CreatePolicy()
method, along with the content type you want to associate.
If you have imported the policy from an XML file, you can find a GUID that uniquely identifies the policy
in the top-level <p:Policy> element. Use this GUID to reliably obtain the correct policy from the policy
catalog.
The following code illustrates how to associate a policy in the catalog with a content type:
Associating a Policy with a Content Type

{
//Access the policy catalog
//Get the policy.

Policy policy = policyCatalog.PolicyList["b6ff57d1-586c-4df5-b781-2a2865b75575"];
//Get the content type

SPContentType docContentType = siteCollection.RootWeb.ContentTypes["Document"];
//Associate the policy with the content type

Policy.CreatePolicy(docContentType, policy);
}
Introducing Document Sets

Many situations require a group of documents to
be managed as a single entity. For example, if a
sales team is working on a Request For Proposal
(RFP), it may create several documents, including
the proposal, staff resumes, customer satisfaction
surveys, and so on. SharePoint includes the
document set feature to satisfy this requirement. A
document set is a specialized folder that includes a
welcome page, extra metadata, and permitted
content types that users can create within the set.
Information management policies can be applied to
all the document sets of a given content type.
You should create a different content type for each type of document set you expect users to create.
Ensure these content types inherit from the default document set content type. For each of these
document set content types, you can specify:
 Allowed Content Types. This list of content types specifies the kinds of documents that users can add
to the document set.
 Default Content. This is a list of document files that are created automatically whenever a user creates
a new document set.
 Shared Columns. This is a list of site columns that all the documents in the document set possess. The
values of these columns are automatically synchronized between all the documents in the document
set.
 Welcome Page: This is the SharePoint page that is displayed whenever a user opens a document set.
You can customize the text and layout of this page and display different shared columns.
Creating Document Sets in Code

You can write code that manipulates content types
by using server-side .NET code, client-side .NET
code, or JavaScript. Use the following APIs in each
case:
 Microsoft.Office.DocumentManagement.Docum
entSets. Use this .NET API for server-side code,
such as code in a SharePoint web part.
 Microsoft.SharePoint.Client.DocumentSet. Use
this .NET API for client-side code, such as code
in a provider-hosted SharePoint app.
 SP.DocumentManagement.js. Use this

JavaScript library for client-side script code, such as code that runs in the browser in a SharePoint app.
Creating a Document Set

In order to create a new document set based on a document set content type, call the
DocumentSet.Create() method. This method requires three parameters:
 Parent Folder. This is the folder in which the document set will be stored.
 Name. This is the display name of the document set.
 Content Type ID. This is a number that uniquely identifies the content type. The content type ID
includes all the IDs of parent content types.
The following code illustrates how to create a document set by using the client-side .NET managed API.
This code runs within a console application:
Creating a Document Set

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.DocumentSet;
namespace Contoso.ConsoleApps
{
class Program
{
static void Main(string[] args)
{
//Get the client context
//Get the site, list and content types collection and load them
Web web = context.Web;
List targetList = web.Lists.GetByTitle("Document Sets");
ContentTypeCollection listContentTypes = targetList.ContentTypes;
context.Load(listContentTypes, types => types.Include (type => type.Id,
type => type.Name, type => type.Parent));
var contentTypes = context.LoadQuery(listContentTypes.Where (c => c.Name == "Document
Set"));
//Get the ID of the first document set content type
ContentType documentSetType = contentTypes.First();
ContentTypeId docSetContentTypeID = documentSetType.Id;
//Use the content type ID to create a new document set based on this content type
DocumentSet.Create(context, targetList.RootFolder, "My New Document Set",
docSetContentTypeID);
}
}
}
Lesson 3
Automating Records Management
When working with large quantities of content, SharePoint administrators require an automatic tool that
can move documents, assets, and other items to the most appropriate folder based on document
properties. Users should be encouraged to be productive by producing new content, but may be
discouraged if they must read complex rules that determine the SharePoint library or folder where the
content must be stored. By using Content Organizer, you can automate these rules so that SharePoint
moves documents into the most appropriate location. This makes it easier to locate documents at any
later time. Document IDs also help users to locate content, because they do not change throughout the
lifecycle of the document, whether they are moved by users, the Content Organizer, information
management policy, or some other component.
Lesson Objectives
After this lesson, you will be able to:
 Describe how the SharePoint Content Organizer can ensure consistent, automatic document
management.
 Write code that creates Content Organizer rules.
 Describe how document IDs can help users to locate content that has moved.
 Create a custom document ID provider to generate IDs in a unique format.
The Content Organizer

In versions of SharePoint earlier than 2010,
developers often wrote code that examined the
properties of a document and moved the
document to a consistent location. Microsoft
recognized this common need to organize content
automatically based on its metadata and, in
SharePoint 2010, added the Content Organizer to
address the requirement. The Content Organizer
enables users to create rules that examine a
document's properties and content type. Each rule
includes a destination where documents that match
the rule will be moved. By using the Content
Organizer, you can make it easier for users to find content, create new folders to organize large numbers
of documents, and be sure that security is implemented consistently, because the Content Organizer can
move documents into folders with the correct permissions applied.
Note: Before you can use the Content Organizer, a site administrator must enable the
Content Organizer site feature.
The Drop Off Library

When you enable the Content Organizer feature, a new document library named Drop Off Library is
added to the site. Content Organizer rules are applied to documents in this library and then the
documents are moved to their final destinations.
If a user places a document in any other document library, the user bypasses all Content Organizer rules.
You can permit users to do this if you are confident that they know where to place documents. In this
configuration, users who do not know the correct location for a document can use the Drop Off Library.
However, you can also configure the Content Organizer to redirect users to the Drop Off Library
whenever they add a document. In this configuration, Content Organizer rules are always enforced.
Content Organizer Settings

In each site, site administrators can control the following settings for the Content Organizer:
 Redirect users to the Drop Off Library. When this setting is enabled, users cannot bypass Content
Organizer rules and must add all new documents to the Drop Off Library.
 Sending to another site. When this setting is enabled, Content Organizer rules can have destinations in
other sites or site collections. These sites should also have the Content Organizer enabled.
 Folder Partitioning. When this setting is enabled, the Content Organizer will create a subfolder
whenever the number of items in a destination library exceeds a number that you specify.
 Duplicate Submissions. With this setting you can specify what happens when a document with a
duplicate name already exists in the destination library. Content Organizer will either create a new
version of the document, if versioning is enabled, or add random characters to the end of the file
name.
 Preserving Context. When this setting is enabled, audit entries and properties in the Drop Off Library
are preserved when the document is moved to the destination.
 Rule Managers. You can specify user accounts as rule managers who can create Content Organizer
rules in the site. Rule Managers must have the Manage Web Site permissions level.
 Submission Points. With this setting, you can configure web services that will accept uploaded
documents and place them in the Drop Off Library, where rules are applied.
Content Organizer Rules and Conditions

When the Content Organizer feature is enabled, SharePoint creates a new list in the site named Content
Organizer Rules. This is the list where rule managers create rules to apply to documents in the Drop Off
Library. For each new rule, the rule manager configures the following settings:
 Rule Name. A descriptive name for the rule.
 Rule Status and Priority. You can use this setting to enable and disable a rule. You can also specify a
priority of 1 to 9. If a document matches two rules, the one with the lower priority number is applied.
1 is the highest priority and 9 is the lowest.
 Submission's Content Type. You can use this setting to match all documents of a particular content
type.
 Conditions. You can create conditions that examine and match individual properties of the document.
The properties that you can match depend on the content type you have selected. You can add
multiple conditions, all of which have to be matched for the rule to apply.
 Target Location. For each rule, you can use this setting to determine the location to which matching
documents will be moved.
Creating Content Organizer Rules

You can write code that modifies Content Organizer
rules by using the
Microsoft.Office.RecordsManagement.RecordsR
epository namespace. You must first obtain an
EcmDocumentRoutingWeb object. This is a
wrapper for the SharePoint web that includes
Content Organizer methods and properties.
Once you have accessed the

EcmDocumentRoutingWeb, you can use the
EcmDocumentRouterRule class to create a new
rule, configure the properties, content type, and
conditions, and save the rule.
The following code illustrates how to create a new Content Organizer rule by using the server-side API:
Creating a New Content Organizer Rule

using (SPSite site = new SPSite("http://dev.contoso.com"))
{
using (SPWeb web = siteCollection.OpenWeb())
{
//Get the document routing web
EcmDocumentRoutingWeb contentOrganizerWeb = new EcmDocumentRoutingWeb(web);
//Get the content type to apply the rule to

SPContentType contentType = web.ContentTypes["Document"];
//Get the final location for the rule

SPList destinationLibrary = web.Lists["Archive"];
//Create the rule

EcmDocumentRouterRule newRule = new EcmDocumentRouterRule(web);
//Set properties for the rule

newRule.Name = "Move all documents to archive";
newRule.Description = "This rule will move every new document from the Drop Off
library " +
"to the Archive library";
newRule.RouteToExternalLocation = false;
newRule.Priority = "9";
//Tie this rule to the right content type

newRule.ContentTypeString = contentType.Name;
//Specify the destination

newRule.TargetPath = destinationLibrary.RootFolder.ServerRelativeUrl;
//Save the new rule

newRule.Update();
}
}
Note: Content organizer rules apply at the web level. You can only export content
organizer rules programmatically.
Introducing Document IDs

Documents in SharePoint can be moved from their
original location by users, information management
policies, Content Organizer rules, and custom
solutions and apps. Sometimes these movements
can prevent users from later finding the documents.
You can use document IDs to mitigate this problem
by generating a static unique identifier for each
document when the document is first created. This
ID will not change if the document is moved for any
reason. If you know the document's ID, you can find
it wherever it is in your SharePoint content
database.
When you use document IDs, SharePoint also generates a static URL for each document that includes the
ID. Like the ID, that static URL does not change later in the document's life. This means that you can link
to the static URL, for example in a web page, and know that the link will not break if the document is
moved. When the link is clicked, SharePoint locates the document and redirects the user to the actual URL
where the document is currently stored.
The document ID service generates IDs only for documents, and not for items or media assets. To receive
a document ID, a document must be based on the Document content type or a content type that inherits
from Document.
Configuring Document IDs

Before SharePoint will assign document IDs, a site collection administrator must activate the Document ID
Service site collection feature. When this feature is enabled, a new site column named Document ID is
added to the site collection. This column is also added to the Document and Document Set content types
and all their child content types. A new page, named Document ID Settings, is added to the Site Settings
page in the top-level site of the site collection. Finally, the Document ID Service, which is responsible for
generating IDs and assigning them to new documents, is started.
In the Document ID Settings page, a site collection administrator can control the following values:
 Assign Document IDs. This setting enables or disables the generation of document IDs for new
documents. If you disable this setting, SharePoint will not remove the IDs or static URLs for existing
documents.
 Begin IDs with the following characters. You can use this setting to apply a prefix to all document IDs.
For example, you could specify the name of the company or division.
 Document ID Lookup Search Scope. When users search for a document ID or click a static URL,
SharePoint must locate the document. To do this it can query the Search Service. This setting specifies
which search scope will be used for this query.
The Search Service can be used by SharePoint to locate documents from a document ID. Search
administrators should consider these queries when they configure the Search Service. For example,
administrators should consider creating a dedicated search scope that includes all destinations within
SharePoint where documents are stored.
Document ID Providers
The Document ID Service uses document ID providers for two purposes:
 To generate new IDs.
 To locate documents from IDs.

Therefore, there are two methods by which a document can be located from its ID:
 Using the Search Service. The Search Service is an excellent and functional method of locating
documents. However, if the document is new, the ID may not be in the index and may not be found.
 Using the Document ID Provider. The provider can include custom code for document location.
Each document ID provider specifies which of these methods is used first.

If you want to create document IDs in a specialized format that cannot be generated by the default
provider, you can write a custom document ID provider. You can also use a custom document ID provider
to implement a custom document location method.
Creating a Custom Document ID Provider

The built-in document ID Provider assigns random
identifiers to each document when it is created. You
can add a prefix in the Document ID Settings page
that will be used for all new document IDs and
static URLs. This is a versatile system, but you may
have unique requirements for document IDs. For
example, you may want to make IDs more
descriptive by including the date and time of
creation, or to import IDs from an external system.
In these situations you can create and install a
custom document ID provider.
Coding a Document ID Provider

To build a custom document ID provider, create a class that inherits from the DocumentIDProvider class
in the Microsoft.Office.DocumentManagement class. In the new class, you must implement three
methods and one property:
 GenerateDocumentId. This method creates the document ID for the list item that is passed. You can
access the properties of the list item, add random numbers, add a GUID or lookup values from
external systems, and use these values to create and return the ID.
 GetDocumentUrlsById. This method performs a custom search routine that does not use the
SharePoint Search service.
 GetSampleDocumentIdText. This method returns a string that illustrates the format of the document
ID.
 DoCustomSearchBeforeDefaultSearch. If this property returns true, the GetDocumentUrlsByID
method is called to find documents before the Search Service. If this property returns false, the
opposite order is used.
The following code illustrates a complete custom document ID provider:
A Custom Document ID Provider

class DocumentIDProvider : DocumentIdProvider
{
private string docIdFormatString = "Contoso{0}";
public override string GenerateDocumentId(SPListItem listItem)

{
if (listItem == null) {
throw new ArgumentNullException("listItem");
}
//Generate a random number for the document ID

Random random = new Random();
int randomNumber = random.Next(100000, 999999);
//Insert the random number into the format string and return the resulting ID
return string.Format(this.docIdFormatString, randomNumber);
}
public override string[] GetDocumentUrlsById(SPSite site, string documentId)

{
List<string> itemUrls = new List<string>();
//Check that the parameters have been supplied

if (site != null && !string.IsNullOrEmpty(documentId))
{
//Run the search for items
itemUrls = DocumentFinder.FindByDocumentId(site, documentId);
}
if (!itemUrls.Any())
{
return null;
}
else
{
return itemUrls.ToArray();
}
public override string GetSampleDocumentIdText(SPSite site)

{
//Return a string that illustrates the format of the document IDs
return string.Format(this.docIdFormatString, "123456");
}
//Indicate that the custom search method will be called before the Search Service
public override bool DoCustomSearchBeforeDefaultSearch
{
get { return true; }
}
Installing and Uninstalling a Document ID Provider

After creating the document ID provider, you must ensure that it is installed and uninstalled when the
solution is activated and deactivated. You can use a feature receiver to execute these actions. To install the
provider, call the static DocumentId.SetProvider() method. To remove the provider and revert to the
default document ID provider, call the static DocumentId.SetDefaultProvider() method.
The following code illustrates how to build a feature receiver that installs and uninstalls a custom
document provider:
Document ID Provider Feature Receiver

public class ContosoDocumentIDProviderFeatureEventReceiver : SPFeatureReceiver
{
public override void FeatureActivated(SPFeatureReceiverProperties properties)

{
//Get the site collection
SPSite site = (SPSite)properties.Feature.Parent;
//Set the new document ID provider
DocumentId.SetProvider(site, new Contoso.ContentManagement.DocumentIDProvider());
}
public override void FeatureDeactivating(SPFeatureReceiverProperties properties)

{
//Get the site collection
//Revert to the default provider
DocumentId.SetDefaultProvider(site);
}
Discussion: Document ID Scenarios

Discuss the following scenarios with the class and
determine how you would implement the
requirements:
Scenario: Integrating Document Libraries

with an External System
Your company's Accounts department uses a third-
party accounting package to record purchases. The
system generates purchase orders as Word
documents. When you save these purchase orders
to the Purchase Orders document library in
SharePoint, you want the document ID to match
the purchase order ID that the accounting package
uses internally. How would you implement this requirement?
Scenario: Generating Bar Codes

Your company wants to generate bar codes that conform to the Code 39 standard for every new
document. How would you implement this requirement?
Scenario: Locating Documents without Using Search

You want to be sure that a new document can be located by its ID, even before the Search Service has
crawled the document.
Lab: Implementing Content Management Functionality

Scenario
The Finance team at Contoso uses a proprietary accounting system to manage sales ledgers and purchase
ledgers. At the same time, invoices are stored in various document libraries on the SharePoint intranet
portal. The team wants to make it easier to correlate invoices on SharePoint with items on the sales
ledger.
To assist the team, you will implement various document management features on the SharePoint
intranet portal. First, you will implement a document ID provider to generate a unique document ID for
every document. The Sales team can record the document ID on the sales ledger, and use the ID to
retrieve the document quickly from SharePoint even if it has been moved. Next, you will configure and
apply an auditing policy that ensures document reading and writing operations are recorded.
Objectives
 Create a custom document ID provider.
 Register a custom document ID provider.
 Create and apply a custom information management policy in a SharePoint feature receiver.
Lab Setup

Exercise 1: Creating a Custom Document ID Provider

Scenario
In this exercise, you will create a custom document ID provider that will implement document IDs in the
same way that finance team's accounting system creates IDs. The IDs include the word "Contoso" and a
random, six digit number. To locate documents with a given ID, you will make use of a class developed by
another team member.
1. Create a New Project and Add a Class
2. Code Document ID Creation
3. Code Custom Searches

4. Complete the Document ID Provider
 Task 1: Create a New Project and Add a Class

1. In Visual Studio, create a new SharePoint Solution project for the document ID provider. Use the
following information:
o Language: Visual C#
o Template: SharePoint 2013 Empty Project
o Name: ContosoDocumentIDProvider
o Location: E:\Labfiles\Starter
2. Use the http://dev.contoso.com site for debugging and configure the project as a farm solution.
3. Add a new class, named DocumentIDProvider to the ContosoDocumentIDProvider project.
4. Add references to the following assemblies to the project:
o Microsoft.Office.DocumentManagement
o Microsoft.Office.Policy
5. Add using statements for the following namespaces to the DocumentIDProvider.cs code file:
o System.Data
o Microsoft.Office.DocumentManagement
6. Set the namespace for the DocumentIDProvider class to Contoso.ContentManagement.
7. Ensure that the DocumentIDProvider class inherits from the DocumentIdProvider class in the
Microsoft.Office.DocumentManagement namespace.
 Task 2: Code Document ID Creation

1. In the DocumentIDProvider class create a new variable. Use the following information:
o Scope: private
o Type: string
o Name: docIdFormatString
o Value: "Contoso{0}"
2. Override the GenerateDocumentId method.
3. In the GenerateDocumentId method, if the listItem parameter is null, throw a new

ArgumentNullException.
4. Create a new Random object named random.
5. Use the random object to generate a random integer between 100,000 and 999,999 and store the
integer in a variable named randomNumber.
6. Use the string.Format() function to insert the randomNumber value into the docIdFormatString
and return the resulting string.

 Task 3: Code Custom Searches

1. In the DocumentIDProvider class, override the GetDocumentUrlsById method.
2. Create and instantiate a new List of string variables names itemUrls.
3. Create an if statement that checks that the site parameter is not null and that the documentId
parameter is not null or an empty string.
4. Add the following code file to the ContosoDocumentIDProvider project:

o E:\Labfiles\C# Code\DocumentFinder.cs
5. In the if statement, pass the site and documentId parameters to the

DocumentFinder.FindByDocumentId method. Store the returned list in the itemUrls variable.
6. If the itemUrls variable has zero strings, return null. Otherwise, return the itemUrls list converted into
an array.
 Task 4: Complete the Document ID Provider

1. In the DocumentIDProvider class, override the GetSampleDocumentIdText method.
2. Use the string.Format() function to insert the string "123456" into the docIdFormatString and
return the resulting string.
3. Override the DoCustomSearchBeforeDefaultSearch property.
4. Ensure that the DoCustomSearchBeforeDefaultSearch property always returns true.
Results: A Microsoft Visual Studio® project with a custom document ID provider class coded and
completed.
Exercise 2: Registering a Custom Document ID Provider

Scenario
Now that you have completed the custom document ID provider for Contoso, you must enable the
SharePoint solution to install and uninstall the provider. You will do this by adding a feature and using a
feature receiver to execute installation and uninstallation code. At this end of this exercise, you will test
the document ID provider.
1. Add a Feature Receiver
2. Set the Document ID Provider on Activation
3. Set the Default Document ID Provider on Deactivation
4. Test the Document ID Provider

 Task 1: Add a Feature Receiver

1. Add a new feature to the ContosoDocumentIDProvider project and name it
ContosoDocIDFeature.
2. Configure the new feature with the following properties:
o Title: Contoso Document ID Provider
o Description: This feature enables the Contoso Document ID Provider

o Scope: Site
3. Add an event receiver to the ContosoDocIDFeature and remove all commented code from the event
receiver.
 Task 2: Set the Document ID Provider on Activation

1. In the ContosoDocIDFeature.EventReceiver.cs code file, add a using statement for the
Microsoft.Office.DocumentManagement namespace.
2. In the ContosoDocIDFeatureEventReceiver class, override the FeatureActivated method.
3. In the FeatureActivated method, cast the properties.Feature.Parent property as a SPSite object

and store it in a variable named site.
4. Call the static DocumentId.SetProvider method. Pass the site object and a new
DocumentIDProvider object as parameters.
 Task 3: Set the Default Document ID Provider on Deactivation

1. In the ContosoDocIDFeatureEventReceiver class, override the FeatureDeactivating method.
2. In the FeatureDeactivating method, cast the properties.Feature.Parent property as a SPSite object

3. Call the static DocumentId.SetDefaultProvider method. Pass the site object as a parameter.
 Task 4: Test the Document ID Provider

1. Start Internet Explorer, browse to the http://dev.contoso.com SharePoint site, and log on with the
following credentials:
o User name: Administrator
2. Activate the Document ID Service feature at the site collection level.
3. Examine the Document ID Settings for the site collection. Notice that you can edit the prefix for
document IDs.
4. Deploy the solution.
5. Examine the Document ID settings for the site collection. Notice that a custom document ID
provider has been configured and that you cannot edit the prefix for document IDs.
6. Add the following document to the Documents library:
o E:\Labfiles\Test Documents\Test Document.docx

7. Add the Document ID column to the current view. Notice that the provider has generated a
document ID for the Test Document that begins with "Contoso".
8. Close Internet Explorer, and return to Visual Studio.
Results: A completed document ID provider in a SharePoint solution.
Exercise 3: Applying a Custom Audit Policy

Scenario
In this exercise you will add code to the SharePoint solution that applies a custom auditing policy to the
Document content type. You will create this policy by using the SharePoint user interface, and export the
policy to an XML file. Your custom code, written in a feature receiver, will import this XML file as a new
policy and apply it to documents. You will also write code that cleans up your changes when the feature is
deactivated.
1. Export an Information Management Policy

2. Create a Feature Receiver
3. Code the Policy Import
4. Code Policy Removal

5. Test the Information Management Policy
 Task 1: Export an Information Management Policy

1. Start Internet Explorer and browse to the http://dev.contoso.com site. Log on with the following
credentials:
2. In Site Settings, access the list of Content Type Policy Templates.

3. Create a new policy. Use the following information:
o Name: Contoso Audit Policy
o Administrative Description: This policy ensures auditing for reading and editing items
o Policy Statement: A policy is applied to this document that audits access
o Enable auditing: selected.
o Opening or downloading documents: selected.

o Editing Items: selected.
4. Export the Contoso Audit Policy to a new folder named Polices in the root of the C: drive.
5. Delete the Contoso Audit Policy from the http://dev.contoso.com site collection.
 Task 2: Create a Feature Receiver

1. Add a new feature to the ContosoDocumentIDProvider project and name it
ContosoAuditingFeature.
2. Configure the new feature with the following properties:
o Title: Contoso Auditing Feature
o Description: Sets up auditing for documents in Contoso sites

o Scope: Site
3. Add an event receiver to the ContosoAuditingFeature and remove all commented code from the
event receiver.
 Task 3: Code the Policy Import

1. In the ContosoAuditingFeature.EventReceiver.cs code file, add a using statement for the following
namespaces:
o System.Xml
o Microsoft.Office.RecordsManagement.InformationPolicy
o System.IO
2. In the ContosoAuditingFeatureEventReceiver class, override the FeatureActivated method.
3. In the FeatureActivated method, cast the properties.Feature.Parent property as a SPSite object

4. Create a new PolicyCatalog object named policyCatalog and pass the site object to the constructor.
5. Create a new XmlDocument object named policyXmlDoc.
6. Load the exported Contoso Audit Policy.xml file into the policyXmlDoc object.
7. Create a new StringWriter object named stringWriter.
8. Create a new XmlTextWriter object named xmlTextWriter by passing the stringWriter object to
the constructor.
9. Write the contents of policyXmlDoc to the xmlTextWriter object.
10. Convert the stringWriter object to a string and store it in a new string variable named policyXml.
11. To import the policy, call the static PolicyCollection.Add() method and pass site and policyXml as
parameters.
12. In the C:\Policies\Contoso Audit Policy.xml file, copy the id value from the first <p:Policy> element to
the clipboard.
13. Use the id value you just copied to retrieve the new policy from the policyCatalog.PolicyList
collection and store it in a new Policy object named newPolicy.
14. Get the Document content type from the root web of the site collection and store it in a new
SPContentType object named docContentType.
15. To add the policy to the Document content type, call the static Policy.CreatePolicy() method and
pass docContentType and newPolicy as parameters.

 Task 4: Code Policy Removal

1. In the ContosoAuditingFeatureEventReceiver class, override the FeatureDeactivating method.
2. In the FeatureDeactivating method, cast the properties.Feature.Parent property as a SPSite object

3. Get the Document content type from the root web of the site collection and store it in a new
SPContentType object named docContentType.
4. To remove the policy from the content type, pass docContentType to the static
Policy.DeletePolicy() method.
5. In the C:\Policies\Contoso Audit Policy.xml file, copy the id value from the first <p:Policy> element to
the clipboard.
6. To delete the policy, call the static PolicyCollection.Delete() method and pass the site collection and
the id value you just copied.
 Task 5: Test the Information Management Policy

1. Start without debugging and authenticate with the following credentials:

o Password: Pa$$w0rd.
2. Open the list of Content Type Policy Templates for the site collection. Notice that the Contoso
Audit Policy has been recreated by the feature receiver.
3. Access the Information Management Policy Settings for the Documents library.
4. Check that the information management policy for the Document content type is Content Audit
Policy.
Results: A SharePoint solution that imports and applies an information management policy when it is
activated.

Discuss the following questions with the students:
 The custom document ID provider you created

assigned documents IDs in the format
"Contoso123456". Is it possible to create these
document IDs by using the default provider?
 You have installed your solution in a site

collection. The audit policy seems to have been
created and assigned to the Document content
type correctly. However no information appears
in the audit logs. What do you think is
prevented the auditing from working correctly?

In this module, you learned about the facilities that SharePoint Server 2013 provides for advanced
document management and how to write code that automates those features.
Review Question(s)
Question: You have created an eDiscovery Center and a new eDiscovery Case. However,
when you create a set and try to access results within the set, you receive an error. You also
cannot create queries on the set. How can you solve this problem?
Statement Answer
True or False: When you enable the Content

Organizer in a site, users must always add their
documents to the Drop-Off Library.
6-1
Module 6
Developing a Publishing Site for Web Content
Contents:
Module Overview 6-1
Lesson 1: Programming with the Web Content Publishing API 6-2
Lesson 2: Developing Page Components for Web Content Publishing 6-10
Lab: Customizing a SharePoint Publishing Site 6-27
Module Overview
Microsoft® SharePoint® Server 2013 has introduced new capabilities for building rich web content
publishing sites. While preserving many of the successful foundational elements of publishing sites,
including page layouts and publishing pages, key improvements have been made in navigation, search
engine optimization, surfacing search-driven content, and support for mobile devices.
In this module, you will learn how to develop web content solutions for publishing sites.
Objectives
 Describe how to utilize the Publishing API to access publishing settings and content.
 Describe how to use and customize page content controls in publishing sites.
6-2 Developing a Publishing Site for Web Content
Lesson 1
Programming with the Web Content Publishing API
The SharePoint Publishing API provides a collection of classes for programmatically accessing the
enhanced capabilities of publishing-enabled sites. In this lesson, you will learn how to work with the
publishing API to deploy and customize publishing settings and content.
Lesson Objectives
 Describe the capabilities of the Publishing API.
 Describe how to access the Publishing API by utilizing the server-side object model.
Introduction to Developing Publishing Solutions

SharePoint provides an API for working with the
special capabilities of publishing sites. Publishing
sites are identified by the activation of publishing-
related features at the site collection and site level.
Any SharePoint site can be enhanced with
publishing features by activating the PublishingSite
and PublishingWeb features at the Site Collection
and Site level respectively. Publishing features are
automatically activated when creating a site
collection by using the Publishing Portal, or a sub-
site by using the Publishing Site template.
The following code example demonstrates how to

activate the publishing features on a site collection and top-level site with PowerShell:
Enable Publishing Features with PowerShell

Enable-SPFeature –Identity 'PublishingSite’ –Url 'http://www.contoso.com’
Enable-SPFeature –Identity 'PublishingWeb’ –Url 'http://www.contoso.com’
Some of the additional capabilities available on sites with publishing feature enabled include:
 Page Layouts and Publishing Pages. In addition to the standard page types such as Wiki pages and
Web Part pages, a new page rendering model is enabled that supports the use of Page Layouts and
Publishing Pages.
 Variations and Device-Specific Targeting. Publishing sites can support multilingual variations in site
content, and can redirect users to the appropriate language content resources based on browser
language settings. Variations and Device Channels can also be used to provide alternative
presentation of content based on mobile device use, or geographic elements such as country or
region.
 Portal and Managed Navigation. Publishing sites utilize unique navigation providers for handling the
special characteristics of publishing sites. Managed Navigation, a new feature introduced in
SharePoint 2013, supports user-friendly URL’s,
 Image Renditions. Optimizing images for publishing sites is an important consideration for
performance. Image Renditions is a new feature in SharePoint 2013 that automatically renders images
Developing Microsoft SharePoint 2013 Advanced Solutions 06-3
to meet preconfigured resolutions, and enables content authors to select appropriate renditions when
embedding media in content.
 Search Engine Optimization. Publishing sites now support auto-generation of site maps, robots
exclusion protocol, canonical URL’s, and SEO meta properties for pages and navigation.
 Cross-Site Publishing. This new feature introduced in SharePoint 2013 utilizes search technology to
allow content in one or more authoring sites to be surfaced in a publishing site. By defining a list or
library as a catalog, cross-site connections can be established that enable a publishing site using the
Content Search Web Parts to display content authored and located in a remote site collection.
SharePoint 2013 has introduced some significant changes and a myriad of new choices for developers
building publishing solutions. In particular, architects, designers, and developers must consider the
following:
 Server-Side vs. Client-Side Programming. SharePoint 2013 has seen significant enhancements in the
capabilities of the Client Side Object Model (CSOM) and the JavaScript Library (JSOM), providing
enhanced access to publishing capabilities that previously could only be accomplished by using
server-side code.
 Solutions vs. Apps. SharePoint 2013 has introduced a new programming model called Apps for
SharePoint. The Solutions and Features Framework is still fully supported, but Microsoft is now
recommending the use of the new app model for many kinds of customizations.
The remainder of this lesson will focus on Page Layouts and Publishing Pages, including provisioning,
configuration of publishing settings through code, and how to work with and customize publishing page
components for use in publishing sites.
Note: Additional web-content management capabilities including Variations, Device

Targeting, Managed Navigation, Cross-Site Publishing, Image Renditions, and Search Engine
Optimization are covered in other modules in this course.
Getting Started with the Publishing API

The Server-side Object Model (SSOM) has been the
traditional foundation for custom solutions built on
SharePoint. Combined with the Solutions and
Features framework, the SSOM continues to provide
the highest level of functionality and customization
available to developers.
To begin working with the server-side publishing

API, you must add a reference to the
Microsoft.SharePoint.Publishing assembly in the
SharePoint root folder, at
%commonfilesfolder%\web server
extensions\15\ISAPI. You will also need to reference
the Microsoft.SharePoint.Publishing root namespace when programming with publishing-related objects.
The Publishing API Hierarchy

For many of the programming tasks in SharePoint, it is common to start by accessing an instance of a
SPSite or SPWeb object. These are considered the root of the SharePoint object model for working
programmatically with site collections and sites. When working with publishing sites, the Publishing API
provides a complementary set of classes, the PublishingSite and PublishingWeb classes, respectively.
Accessing the publishing features of a site collection or site commonly requires provisioning an instance
of one of these objects.
In the following code example demonstrates how to instantiate a PublishingSite and PublishingWeb
object for accessing publishing settings on a site collection:
Create a PublishingSite and PublishingWeb Object

using Microsoft.SharePoint;
using Microsoft.SharePoint.Publishing;
…
SPSite site = SPContext.Current.Site;

if (PublishingSite.IsPublishingSite(site))
{
// get an instance of the publishing site
PublishingSite pubSite = PublishingSite.GetPublishingSite(site);
SPWeb web = SPContext.Current.Web;

if (PublishingWeb.IsPublishingWeb(web))
{
// get an instance of the publishing web
PublishingWeb pubWeb = PublishingWeb.GetPublishingWeb(web);
}
}
Working with Page Layouts

Page Layouts in publishing sites are deployed side-
by-side with masterpages in the Site Master Page
Gallery. This gallery is located in the site collection
at "/_catalogs/masterpages".
Provisioning Page Layouts with a Module

Element
Deploying a Page Layout using a Module element
has changed slightly in SharePoint 2013 when
compared with previous versions. The changes
include some new attributes available on the File
element included within a Module, and some
additional properties that need to be set when
deploying the Page Layout file due to changes in settings related to the Master Page Gallery.
The following code example demonstrates how to provision a Page Layout by using a Module element:
Module Element to Provision a Page Layout

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Module Name="PageLayouts" Url="_catalogs/masterpage">
<File Path="PageLayouts\ProductArticle.aspx" Url="ProductArticle.aspx"
Type="GhostableInLibrary" ReplaceContent="TRUE" Level="Published">
<Property Name="Title" Value="Product Article" />
<Property Name="MasterPageDescription" Value="Article layout for Contoso Product
News and Events." />
<Property Name="ContentType" Value="Page Layout" />
<Property Name="PublishingAssociatedContentType" Value=";#Article
Page;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF3900242457E
FB8B24247815D688C526CD44D;#" />
<Property Name="PublishingHidden" Value="FALSE" />
<Property Name="HtmlDesignAssociated" Value="FALSE" />

</File>
</Module>
</Elements>
As demonstrated above, two new attributes are available on the File element of a Module:
 ReplaceContent. This attribute now allows the contents of an existing file to be replaced with the
contents of the new file.
 Level. This attribute now allows specifying the version setting when provisioning the file as Draft or
Published.
Some new properties are also available for Page Layouts that should be included:
 PublishingHidden. Indicates whether the page layout is displayed to users when creating new pages
through the SharePoint UI.
 HtmlDesignAssociated. Indicates whether the Page Layout is associated with an HTML layout file.
When creating Page Layouts through the Design Manager, this association is set to TRUE by default.
To separate a Page Layout or Master Page association with an HTML template, set this value to FALSE.
Working with Publishing Pages

Publishing sites have a unique page rendering
architecture that combines master pages, page
layouts, and publishing page instances. Publishing
sites also impose certain restrictions, such as
requiring that all publishing pages in a site reside in
the Pages library.
Provisioning Pages with a Module

Element
A common way to create publishing pages is to
deploy them by using a Module element in a
SharePoint solution.
The following code example demonstrates a module element to provision a publishing page:
Module Element to Provision a Publishing Page

<Module Name="Pages" Url="Pages">
<File Path="Pages\About.aspx" Url="About.aspx" Type="GhostableInLibrary"
IgnoreIfAlreadyExists="TRUE">
<Property Name="Title" Value="About Contoso"/>
<Property Name="PublishingPageLayout"
Value="~SiteCollection/_catalogs/masterpage/BlankWebPartPage.aspx, Blank Web Part page"/>
<Property Name="ContentTypeId"
Value="0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF390064DEA0
F50FC8C147B0B6EA0636C4A7D400B2BBEE3355EE1141BAE9DA2E12C5B1E4" />
</File>
</Module>
</Elements>
Provisioning a publishing page requires specifying at least two mandatory properties:
 PublishingPageLayout. This property requires specifying the page layout to associate with the
publishing page in the format {server-relative URL, title}.
 ContentTypeId. This property requires the Content Type ID of the content type to be associated with
the publishing page.
In addition, depending on the content type, you can specify additional properties for any of the fields
included in the content type.
Note: SharePoint App Webs do not support deploying Module elements to the Host Web,
and do not support Publishing features on the App Web. When attempting to deploy a
publishing page to the Host Web from a SharePoint App, the publishing page must be
provisioned by using code.
Provisioning Pages with Code

Publishing pages can also be provisioned with code. This is the approach used when creating new pages
through the SharePoint UI.
The following code example demonstrates how to provision a publishing page by using the Publishing
API:
Provisioning and Publishing Page with Code

// Get the page layout to use.
PublishingSite pubSite = PublishingSite.GetPublishingSite(site);
PageLayout pageLayout = pubSite.PageLayouts[String.Format("{0}/catalogs/masterpage/{1}",
site.Url, "BlankWebPartPage.aspx"];
// Create the new page.

PublishingPageCollection pagesLib = pubWeb.GetPublishingPages();
PublishingPage newPage = pagesLib.Add("newPage.aspx", pageLayout);
newPage["Title"] = "New Page";
newPage.Update();
// Publish and approve the new page.

newPage.File.CheckIn(comment);
newPage.File.Publish(comment);
newPage.File.Approve(comment);
Provisioning publishing pages requires an instance of a PublishingWeb object, which provides a number
of overloads for the AddPublishingPage method.
Scheduling Page Publishing

Publishing sites support a feature that allows page visibility to users to be scheduled with a start and an
end date. To support the feature, major and minor versioning must be configured on the Pages library,
and Content Approval must be enabled.
The following code example demonstrates how to enable scheduling on the Pages library of a publishing
site:
Enable Scheduling for Publishing Pages

SPList pagesLib = pubWeb.PagesList();
If (!pagesLib.EnableModeration)
{
pagesLib.EnableMinorVersions = true;
pagesLib.EnableModeration = true;
pagesLib.Update();
}
pubWeb.EnableScheduling(pagesLib);
The scheduling capability is supported by a timer job that checks the PublishingStartDate and
PublishEndDate columns respectively, and automatically updates the content approval status on an item.
The PublishingPage class provides properties to update the start and end dates, and to trigger scheduling
on a page item.
The following code example demonstrates how to schedule publishing on a page programmatically:
Schedule Page Content Approval

PublishingPage pubPage = pubWeb.GetPublishingPages(query, 1);
pubPage.StartDate = startDate;
pubPage.EndDate = endDate;
pubPage.ListItem.SystemUpdate(false);
pubPage.Schedule();
It is important to update the underlying list item after updating the StartDate and EndDate properties on
a PublishingPage item. After updating the item, call the Schedule method.
Working with Navigation Settings

SharePoint publishing sites have unique navigation
capabilities that differ from non-publishing sites. A
common requirement when developing publishing
solutions is the need to programmatically configure
navigation settings.
Working with Publishing Navigation

Classes for accessing navigation settings are
distributed across two namespaces:
 Microsoft.SharePoint.Publishing
 Microsoft.SharePoint.Publishing.Navigation
The following code example demonstrates how to import the correct namespaces for working with
publishing navigation settings:
Importing Publishing Navigation Namespaces

using Microsoft.SharePoint.Publishing.Navigation;
Navigation Providers
Publishing sites have two built-in navigation objects:
 Global Navigation (referred to as Top Navigation in non-publishing sites)
 Current Navigation (referred to as Left Navigation or Quick Launch in non-publishing sites)
Each navigation object can be configured separately, enabling publishing sites to combine navigation
models according to requirements. In addition to the PortalProvider carried forward from previous
versions of SharePoint (now referred to as Structured Navigation), SharePoint 2013 includes a new type of
navigation provider called Managed Navigation that utilizes the Managed Metadata Service. Managed
Navigation works in conjunction with other new web content management features, including Friendly
URLs and Cross-Site Publishing with Catalogs. Managed Navigation utilizes the TaxonomyProvider.
The following code example demonstrates how to set the navigation provider for Global and Current
Navigation:
Configuring Navigation Providers

WebNavigationSettings webNav = new WebNavigationSettings(web);
webNav.GlobalNavigation.Source = StandardNavigationSource.TaxonomyProvider;
webNav.CurrentNavigation.Source = StandardNavigationSource.PortalProvider;
Depending on the navigation provider selected, additional settings are available.
Working with Structured Navigation Settings

When selecting structured navigation (use of the PortalProvider), additional settings are accessed by using
the PublishingWeb.Navigation property to access an instance of a PortalNavigation object. Some of the
properties available for the Global and Current navigation options are:
 Include Sub-Sites. This setting indicates whether sub-sites should be automatically added to the
navigation items.
 Include Pages. This setting indicates whether new pages should be added automatically to navigation.
 Dynamic Child Limit. This setting limits the number of child navigation items displayed.
The PortalNavigation object also provides methods for setting the sort order of navigation items, and for
adding additional manual items to the collection of navigation items.
The following code example demonstrates setting navigation options for structured navigation:
Structured Navigation Settings

PortalNavigation portalNav = pubWeb.Navigation;
// settings for global navigation

portalNav.InheritGlobal = false;
portalNav.GlobalIncludeSubSites = true;
portalNav.GlobalIncludePages = false;
portalNav.GlobalDynamicChildLimit = 20;
// settings for current navigation

portalNav.InheritCurrent = false;
portalNav.CurrentIncludeSubSites = false;
portalNav.CurrentIncludePages = true;
portalNav.CurrentDynamicChildLimit = 20;
// navigation sorting
portalNav.OrderingMethod = OrderingMethod.Automatic;
portalNav.AutomaticSortingMethod = AutomaticSortingMethod.Title;
pubWeb.Update();
web.Update();
Additional Reading: For more information on programming the

Microsoft.SharePoint.Publishing.Navigation.PortalNavigation class, read the class documentation
on MSDN at http://go.microsoft.com/fwlink/?LinkId=321107.
Working with Managed Navigation Settings

When selecting structured navigation (use of the TaxonomyProvider), additional settings are accessed by
using the WebNavigationSettings. Similar to structured navigation, new pages can be added automatically
to navigation settings; however, settings related to sort order are specified as properties on the
Navigation terms directly.
The following code example demonstrates updating navigation settings for managed navigation:
Managed Navigation Settings

WebNavigationSettings webNav = new WebNavigationSettings(web);
// set managed navigation settings

webNav.AddNewPagesToNavigation = true;
webNav.CreateFriendlyUrlsForNewPages = true;
// connect managed navigation to a Navigation Term Set

webNav.GlobalNavigation.TermStoreId = termStoreId;
webNav.GlobalNavigation.TermSetId = termSetId;
webNav.CurrentNavigation.TermStoreId = termStoreId;
webNav.CurrentNavigation.TermSetId = termSetId;
webNav.Update();
web.Update();
Additional Reading: For more information on programming the

Microsoft.SharePoint.Publishing.WebNavigationSettings class, read the class documentation on
MSDN at http://go.microsoft.com/fwlink/?LinkId=321108.
Lesson 2
Developing Page Components for Web Content
Publishing
SharePoint provides developers with a combination of techniques to customize the presentation and
behavior of content, without requiring extensive editing of master pages or page layouts. In this lesson,
you will learn how to create and deploy page components for web content publishing sites, including
field controls, web parts, delegate controls, and custom user actions. This lesson will also introduce the
new SharePoint 2013 page components, including App Parts and the new JSLink property.
Lesson Objectives
 Describe the components involved in rendering a Publishing Page

 Dynamically load controls into publishing pages with delegate controls.
 Dynamically inject JavaScript into publishing pages with the ScriptLink control.
 Customize the display and behavior of page fields with custom field controls.
 Customize the display and behavior of fields with the JSLink property and client-side templates.
The Publishing Site Page Model

In a SharePoint publishing site, the layout and
content of publishing pages is determined by three
components:
 Master pages. A master page defines the page
components that are common to all pages in
the publishing site, such as navigation menus,
sign in controls, and search boxes. The master
page also defines the look and feel of the site
as a whole, through links to CSS files and
JavaScript files. Master pages include
placeholders, into which pages that reference
the master page can insert content.
 Page layouts. A page layout is effectively a template for a particular type of page. A page layout is an
ASPX page that contains HTML markup and content controls such as page field controls, or web
parts. When a page is rendered, markup and controls contained within content placeholders are
merged with the master page.
 Page content. Content for publishing pages is stored as data in a SharePoint list, where each row of
list data represents a publishing page. When a page is rendered, the content from each field in the list
item is displayed by the corresponding field control in the page layout.
Understanding Master Pages

A SharePoint master page is an ASP.NET master page. There are no differences between how master
pages work in SharePoint and how master pages work in any other ASP.NET web application. A
SharePoint master page contains the following types of content:
 HTML elements that define the overall structure of the page.

 Various SharePoint and ASP.NET controls, such as the SharePoint Welcome menu control and the
ASP.NET ScriptManager control.
 Links to CSS style sheets and JavaScript files.
 Several ASP.NET ContentPlaceHolder controls, into which page layouts or web part pages can insert
content.
 Default content for some of the ContentPlaceHolder controls.
Understanding Page Layouts

A page layout is an ASPX page. Because page layouts are designed to work with master pages, all the
content in page layouts is contained within ASP.NET Content controls. Each Content control specifies a
ContentPlaceHolderID value, which indicates the ContentPlaceHolder control in the master page into
which the content should be inserted when the page is rendered.
Each page layout is based on a content type. The content type defines the fields that must be included on
the page. For example, suppose you want to create a page layout that includes a title, two columns of
text, and an image. The corresponding content type might include fields named Title, Column1Text,
Column2Text, and PageImage. The page layout would then include field controls to render the values of
each of these four fields.
The following code example shows how field controls are placed within content controls in a page layout:
Content Controls and Field Controls

<asp:Content ContentPlaceHolderID="PlaceHolderPageTitle" runat="server">
<SharePoint:FieldValue id="PageTitle" FieldName="Title" runat="server" />
<asp:Content>
When a user creates a new page based on a particular page layout, they are simply creating a new list
item with the relevant content type. The user provides values for each of the fields defined by the content
type. The page layout and the master page together determine how the content provided by the user is
rendered.
Page Content Controls and Components

SharePoint provides a wide variety and a very
flexible set of content control types that can be
used and extended to insert content in the page-
rendering process. Not all content controls are
available in all programming models, however, so
choosing the appropriate content control to meet
the specific needs of your application is important.
Some of the core types of content controls available
for custom solutions include:
 Fields Controls. Field controls provide the ability

to wrap a Field Type with custom display or
editing behavior. Field controls are only
supported in full-trust solutions.
 Delegate Controls. A delegate control is a placeholder for content controls that are loaded
dynamically at runtime. Delegate controls allow content controls to be deployed as a feature and
loaded into a page without requiring changes to the master page or page layout. Delegate controls
are only supported in full-trust solutions.
 Server Controls and Web Parts. Server Controls and Web Parts provide a completely custom and
dynamic rendering of content from virtually any data source, and are the ‘Swiss Army knife’ of
content controls. Server controls must be added directly to a master page or page layout. Web Parts
can be added dynamically at runtime, when contained within a Web Part Zone. Web Parts are
typically full-trust solutions; however, SharePoint 2010 added the ability to write Web Parts as part of
a Sandbox solution. Sandbox solutions have now been deprecated in SharePoint 2013 in favor of the
new App model. Custom server controls are not supported in the app model.
 Custom Actions. These allow applications to register custom commands for display at select locations,
such as the ribbon menu, the list item edit control block, and site actions. The ScriptLink control
allows JavaScript links or script blocks to be inserted dynamically into a master page. Custom actions
are supported from full-trust and sandbox solutions, and can be created either declaratively, or
programmatically by using the client-side object model from SharePoint Apps.
 App Parts. App Parts are a new kind of control introduced in SharePoint 2013 as part of the app
model. The app model does not support the deployment of Web Parts to the Host web as part of an
app. An App Part utilizes an IFrame to display a remote page hosted by a SharePoint app. The user
experience of adding an App Part to a page is similar to a Web Part, and is available from the ribbon
menu when editing a page.
 JSLink / Client Templates. These are new to SharePoint 2013, and are very similar to Field Rendering
Controls; however, they are implemented in JavaScript and run client-side. A new JSLink property is
provided to link to JavaScript files that implement rendering script on specific objects including Fields,
Lists, Views, and some Web Parts.
It is not uncommon to see advanced solutions utilize many of these content controls together to satisfy
requirements. With a growing emphasis on client-side programming, the new SharePoint 2013 App
model, and Microsoft’s strong push towards moving customers to Office 365 and SharePoint Online, it is
important when considering customizations for developers to consider all alternatives when selecting the
best solution.
Working with Field Controls

Field controls are used to provide a customized
display and editing experience for field types. An
important distinction between Field controls and
Web Parts is where the data is stored. Field controls
are not responsible for storing content. Each time a
new publishing page is created, a new item is
added to the Pages library within a site. Based on
the content type associated with the page layout,
each page will have a set of field values. Field
controls are configured to support a specific field
on a page, and automatically bind to the field’s
value for the current page item.
Developing a Field Control

Developing a custom field control is done in two parts:
 Rendering Template. A rendering template is typically a user control responsible for rendering the
display or edit views of a field.
 Field Control Class. The field control class is responsible for reading and writing the field value
between the page field and the associated rendering template.
Rendering Templates
Rendering templates are user controls that contain a RenderingTemplate tag. Rendering templates are
associated with a Field Control class based on the value of the ID property. Inside the <Template>
element can be a mix of HTML <div> or <table> tags for layout purposes, and any ASP.NET controls
necessary to present the display or editing experience for the user. The user control is not responsible for
implementing the logic to read and write the values of the controls it hosts; this is done by the Field
Control class.
The following example demonstrates the rendering template control tag:
Rendering Template
<SharePoint:RenderingTemplate ID="ContosoProductCodeRenderingTemplate" runat="server">
<Template>
<asp:TextBox ID="ProductCodeTextBox" runat="server" />
</Template>
</SharePoint:RenderingTemplate>
User controls that contain a RenderTemplate tag must be deployed to the 15\Template\ControlTemplates
folder, and must exist in the root of this folder in order to be detected by SharePoint.
Best Practice: It is generally recommended to deploy custom files to the SharePoint root
folder path under a solution-specific sub-folder in order to separate out-of-box files from custom
solutions. In the case of rendering templates, SharePoint will only inspect the root folder, and will
not search child folders. User control files containing rendering templates must be deployed to
the root folder. To reduce the risk of file naming conflicts, you should prefix your user control file
names with a solution-specific identifier.
Field Control Classes

You create a field control class by inheriting from a base class named BaseFieldControl or any child class
derived from BaseFieldControl; this includes the out-of-box field controls that you can sub-class and
further customize.
All field controls must have the following overrides:
 DefaultTemplateName. The default template name returns the ID of the rendering template that will
be loaded to support field control.
 CreateChildControls. This is a standard method for any server control; however, you don’t create
controls. In field control classes, you reference the TemplateContainer property provided by the base
class to call the FindControl method to get a reference to any controls hosted in the rendering
template.
 Value. This implementation is used to get and set the field value, provided by the base class as
ItemFieldValue, and get and set the appropriate control values hosted in the rendering template.
The following example demonstrates the basic structure of a field control class:
A Simple Field Control Class

public class ProductCodeFieldControl : BaseFieldControl
{
protected TextBox ProductCodeTextBox;
protected override string DefaultTemplateName

{
get { return "ContosoProductCodeRenderingTemplate"; }
}
protected override void CreateChildControls()

{
base.CreateChildControls();
ProductCodeTextBox = (TextBox)
this.TemplateContainer.FindControl("ProductCodeTextBox");
}
public override object Value

{
get
{
this.EnsureChildControls();
return ProductCodeTextBox.Text;
}
set
{
ProductCodeTextBox.Text = (string) this.ItemFieldValue;
}
}
}
The core logic of a field control class is initiated by overriding the Value property. The get method is
called just before SharePoint needs to update the page field on the associated content item. The set
method is called when a user opens a page in edit model in order to initialize the controls in the
rendering template that will be shown to the user.
Note: SharePoint field types are serialized and stored as a raw text string. For simple field
type objects such as Text, the field value can be read and set directly. For more complex types,
the raw string value may be a concatenation of sub-strings. For example, a URL field type is a
combination of the URL display text, and the URI. Field types that require special encoding
typically provide a special field value class for reading and writing the raw field value (for
example, SPFieldUrlValue). If your field control class supports binding to many field types, it is
your responsibility as a developer to implement defensive coding techniques to determine the
system type of the ItemFieldValue in order to read and write the field value correctly.
Deploying your completed solution requires placing the assembly containing the custom field control
class to the Global Assembly Cache (GAC) on all SharePoint front-end servers, and registering the control
as a SafeControl in the web.config. This is best accomplished by packaging the assembly and the
rendering templates in a SharePoint solution file so they can be installed together into the SharePoint
farm. The solution package will also ensure that the SafeControl entry is added properly.
Note: Due to the restriction that field controls deploy to the SharePoint file system, they
must be deployed as a Farm-trust solution and are not supported in sandbox solutions or from
SharePoint apps.
Adding a Field Control to a Page Layout

The final step is to add the field control to a page layout. At the top of the page layout, you need to
register the namespace and assembly containing the custom field control class. Then you can add the
appropriate field control tag within the body of the Page Layout markup. This will normally be within
PlaceholderMain.
The following example demonstrates adding a field control to a page layout:
Adding a Field Control to a Page Layout

<%@ Register Tagprefix="Contoso" Namespace="Contoso.Website.WebControls"
Assembly="Contoso.Website.WebControls" %>
...
<Contoso:ProductCodeFieldControl runat="server" FieldName="ContosoProductCode />
Working with Web Parts

Web Parts are a common and flexible way to add
content to site pages. In addition to field controls,
Web Parts are commonly added to publishing
pages to support dynamic content rollups, forms, or
other user interface features found on web sites.
Web Parts are based on ASP.NET server controls,
with the added benefit of supporting the ability to
add them dynamically to a page through the
SharePoint user interface, or programmatically.
Web Part Manager

The SPWebPartManager is a control that that is
responsible for managing all the Web Part controls,
functionality, and events that occur on a web page. This includes things like tracking which zones each
Web Part is in, and the connections between Web Parts.
The following example demonstrates the tag for adding a Web Part Manager control:
Web Part Manager Control

<WebPartPages:SPWebPartManager runat="Server"/>
In order to host a web part, a page must have an instance of this control, so it is most commonly found in
the site master page. All out-of-box SharePoint master pages include this control. If you are working with
a custom master page, confirm that this control is included in order to support web parts in your solution.
Web Part Zones

Web part zones are containers that are used to group and align web parts on a page. A WebPartZone
control serves two important functions; it provides the user interface when a page is in edit mode so that
users can dynamically add web parts to the page, and it provides a deployment target that developers can
use to provision web parts programmatically on a page.
The following is an example of a Web Part zone that can be added to a Page Layout to host Web Parts:
Web Part Zone

<WebPartPages:WebPartZone PartChromeType="None" ID="HeaderZone" runat="server"
Title="Header">
<ZoneTemplate></ZoneTemplate>
</WebPartPages:WebPartZone>
Web parts are not required to be contained in a WebPartZone, and can be embedded directly within a
content placeholder just like any other ASP.NET server-side control. The disadvantage of this approach is
that web parts cannot be edited through the SharePoint user interface, participate in web part
connections, or be accessed programmatically through code.
Best Practice: It is recommended that when embedding a web part in page layouts or
pages, that the part always be contained in a web part zone. The exception to this rule is when
adding web parts to a master page that does not support web part zones.
Additional Reading: For more information about Web Part Zones, read the WebPartZone
Class documentation on MSDN at http://go.microsoft.com/fwlink/?LinkId=321110.
Adding a Web Part to a Page Layout

Web Parts can be added to a page or page layout in one of three ways:
 Embedded Control Tag. Add the Web Part directly to a page or page layout by using an HTML tag.
 AllUsersWebPart Element. Add the AllUserWebPart element within a File Module.
Embedded Control Tag

Control tags provide the ability to add a control reference by embedding markup directly in a master
page, page layout, or site page. Each control tag also provides the ability to specify the values of any
properties found on the control (for example, Title). All web parts inherit a set of standard properties from
a base class, but developers can add custom properties that are specific to each web part.
Additional Reading: For a description of the standard properties available on all web
parts, read about the WebPart Class on MSDN at http://go.microsoft.com/fwlink/?LinkId=321111.
The following example demonstrates adding a Register tag for a control assembly. This tag should be
placed at the top of the file, and is required to add any control contained within the specified namespace
and assembly to the page layout or site page:
Registering a Control Assembly

<%@ Register
Tagprefix="WebPartPages"
Namespace="Microsoft.SharePoint.WebPartPages"
Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c"
%>
The following demonstrates how to insert a Script Editor web part within a web part zone of a page layout
or site page:
Script Editor Web Part Control Tag

<WebPartPages:WebPartZone runat="server" Title="Header" ID="HeaderZone"
FrameType="TitleBarOnly">
<ZoneTemplate>
<WebPartPages:ScriptEditorWebPart runat="server"
Title="Script Editor"
ID="Control GUID"
__WebPartId="{Web Part GUID}">
</WebPartPages:ScriptEditorWebPart>
</ZoneTemplate>
</WebPartPages:WebPartZone></WebPartPages:ScriptEditorWebPart>
AllUsersWebPart Element
The AllUsersWebPart element can be used within a Module to provision an instance of a web part on a
page layout or page.
The following example demonstrates how to add the AllUsersWebPart element when provisioning a Page
Layout:
AllUsersWebPart Element
<Module Name="PageLayouts" Url="_catalogs/masterpage">
<File Path="PageLayouts\ProductArticle.aspx" Url="ProductArticle.aspx"
Type="GhostableInLibrary">
<Property Name="Title" Value="My Custom Article Page" />
<Property Name="MasterPageDescription" Value="This is my custom Article page for
SharePoint 2010" />
<Property Name="ContentType"
Value="$Resources:cmscore,contenttype_pagelayout_name;" />
<Property Name="PublishingAssociatedContentType"
Value=";#$Resources:cmscore,contenttype_articlepage_name;;
#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC3DB064584E219954237AF3900242457EFB8B2
4247815D688C526CD44D;#" />
<AllUsersWebPart WebPartZoneID="Right" WebPartOrder="1">
<![CDATA[
<webParts>
<webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
<metaData>
<type
name="Microsoft.SharePoint.WebPartPages.ScriptEditorWebPart, Microsoft.SharePoint,
Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" />
<importErrorMessage>Could not import</importErrorMessage>
</metaData>
<data>
<properties>
<property name='Title’>Script Editor</property>
<property name="ChromeType" type="chrometype">None</property>
</properties>
</data>
</webPart>
</webParts>
]]>
</File>
</Module>
</Elements>
Programmatically
When deploying publishing site customizations such as a new Web Part control, it is common to want to
provision instances of the web part on existing pages. Using the WebPartManager control allows adding
web parts programmatically to any WebPartZone.
The following example demonstrates how to add a web part to a page programmatically by using the
page’s web part manager control:
Add Web Part to a Page Programmatically

{
SPSite site = (SPSite)properties.Feature.parent;
using (SPWeb web = site.RootWeb)
{
SPFile page = web.GetFile("Pages/Home.aspx");
page.CheckOut();
using (SPLimitedWebPartManager wpm =

page.GetLimitedWebPartManager(PersonalizationScope.Shared))
{
ScriptEditorWebPart sewp = new ScriptEditorWebPart();
wpm.AddWebPart(sewp, "Header", 0);
page.CheckIn(String.Empty);
}
}
Working with Client Web Parts

Client Web Parts are new in SharePoint 2013, and
are part of the new App model. Sometimes referred
to as App Parts, the Client Web Part is one of the
few elements of a SharePoint App that are
provisioned to the Host Web rather than the App
Web.
The new ClientWebPart is a server-side web part

included with SharePoint 2013 that hosts an IFrame
(and a number of security validation checks) that is
configured to display a remote page hosted in the
App Web. Each Client Web Part provisioned into
the Host Web by an App essentially provides a set
of parameters required to configure an instance of the ClientWebPart.
The following code example demonstrates how to include an App Part in a page layout or site page:
Adding a ClientWebPart to a WebPartZone

<WebPartPages:WebPartZone runat="server"Title="Header" ID="HeaderZone"
FrameType="TitleBarOnly">
<ZoneTemplate>
<WebPartPages:ClientWebPart runat="server"
Name="ClientWebPart"
Title="Publishing Web Settings"
DefaultWidth="350"
DefaultHeight="900">
<Content Type="html" Src="~appWebUrl/Pages/PubSettings.aspx?{StandardTokens}"
<Properties></Properties>
</WebPartPages:ClientWebPart>
</ZoneTemplate>
The Content element is responsible for identifying the source page to display inside the IFrame hosted by
the control. Custom properties can also be defined for the web part, and are passed to the remote page
by adding additional parameter tokens in the URL configured for the Content element’s Src attribute.
Since all App Parts are provisioned by using a standard out-of-box ClientWebPart, and configured
through properties on the web part, they can be provisioned in exactly the same way: by embedding the
web part tag directly into the page layout or site page, or by using the AllUsersWebPart element as
demonstrated in the topic on Working with Web Parts.
Working with Delegate Controls

Delegate controls provide an alternative to directly
adding user controls or server controls to an .ASPX
page. Delegate controls are placeholders for
controls that are dynamically loaded and inserted
into a page at runtime during page rendering.
Adding a Delegate Control

Delegate controls can be added to master pages
and page layouts.
The following example demonstrates the markup

inserted into a master page or page layout to
identify the position of the delegate within the
page:
Delegate Control Markup

<SharePoint:DelegateControl runat="server" ControlId="PageHeader" AllowMultiple="true">
</SharePoint:DelegateControl>
Delegate controls include a number of properties:

 ControlId (Required). The value of this attribute must be unique, and is used to determine the
association with controls that should be loaded for each delegate.
 AllowMultiple. This value determines whether the delegate control will select and load a single control
or support loading multiple controls. Selection of controls and rendering is determined by the
sequence number, with the lowest number receiving the highest priority. The default is false.
 Scope. Indicates the scope of the delegate control, which can be Farm, WebApplication, Site, or Web.
By default, the scope applies to all. When a developer registers a control for a delegate control, the
associated scope of the feature will correlate to the scope of the delegate control.
The out-of-box SharePoint master pages make liberal use of delegate controls as a way to customize
many page elements through the use of features. The following is a list of some of the standard delegate
controls available in SharePoint 2013. The delegate controls highlighted in bold are new to SharePoint
2013.
 AdditionalPageHead
 GlobalSiteLink0
 GlobalSiteLink1
 GlobalSiteLink2
 PublishingConsole
 PageHeader
 TopNavigationDataSource
 TreeViewAndDataSource
 PageFooter
 QuickLaunchDataSource
 SmallSearchInputBox
 GlobalNavigation
 SuiteBarBrandingDelegate
 SuiteLinksDelegate
 PromotedActions
Developers can use the out-of-box delegate controls, or can implement custom delegate controls when
deploying custom master pages or page layouts. Be aware that implementing a custom delegate control
will only customize pages based on the customized master page or page layout.
Registering Controls
Controls are registered using a CAML element that is deployed as part of a Feature, and support
registering either a user control or a server control. When registering a user control, the control must be
deployed to the SharePoint server file system under the \15\Template\Layouts\ControlsTemplates folder.
User controls can only be loaded from a file system, and the ControlTemplates folder is already included
in the SafeControls section of the SharePoint web.config.
The following example demonstrates a <Control> element in CAML:
Registering a User Control

<Control Id="PageHeader" Sequence="10"
ControlSrc="~/_ControlTemplates/ContosoPageHdr.ascx" />
<Control Id="PageHeader" Sequence="50"
ControlClass="Contoso.Website.Delegates.PageHdr"
ControlAssembly="Contoso.Website.Delegates, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=…"/>
</Elements>
Registering a control requires the following properties:
 Id. The Id value is used to register the control with any delegate control with the same name.
 Sequence. The sequence number determines the loading priority for the control. A lower number
means the control will load before another control with a higher number. If two controls have the
same sequence number, the choice of ordering is arbitrary.
If registering a user control, you must specify the control location:
 ControlSrc. The value of this property contains the location of the user control to load.
If registering a server control, then you must specify the assembly and class that implement the control.
The assembly must be deployed to the GAC, and registered as a SafeControl in the SharePoint web.config
for all content web applications.
 ControlClass. The full name, including namespaces of the control class.

 ControlAssembly. The fully-qualified assembly name.
Delegate controls are not supported by sandbox solutions, and are not supported in the new SharePoint
App model.
Note: If you examine built-in SharePoint 2013 master pages, you will notice that delegate
controls and various other page elements are wrapped by AjaxDelta controls. These AjaxDelta
controls are part of the Minimal Download Strategy (MDS) feature in SharePoint 2013. Essentially,
MDS ensures that only content that has changed, rather than all content within an element, is
downloaded through Ajax.
Working with ScriptLink Custom Actions

JavaScript is playing an increasingly important role
in modern web sites and applications. As developers
transition to increased client-side programming,
often inserting a JavaScript link or block into a page
is all that is required to complete a page
customization.
There are a number of ways to include a JavaScript

reference in a SharePoint page:
 Add to Master Page. Similar to linking

JavaScript into any HTML page, a developer or
designer can insert a <script> tag directly in
the master page. The problem with this
approach is that it requires customizing the master page, which may not be feasible for features or
apps that can be dynamically activated or added to any SharePoint site.
 Use a Delegate Control. As we saw previously, delegate controls can dynamically load user controls or
server controls. These controls can register a JavaScript reference using the
Page.ClientScript.RegisterClientScriptBlock method. This approach requires a farm-trust solution in
order to deploy the control. This approach is not supported in SharePoint Online.
 Use the ScriptLink Control with a Custom Action. Custom actions provide an extensibility point for
adding custom commands to the SharePoint UI, such as the ribbon menu or a list ECB menu. It also
supports a location called ScriptLink that is capable of inserting a JavaScript link or block into the
header area of a SharePoint master page. This approach is supported as full-trust, a sandbox solution,
or the new SharePoint 2013 App model. This approach is supported in SharePoint Online as either a
sandbox solution (using CAML) or programmatically from a SharePoint App.
When comparing the three options noted above, using the ScriptLink control with a custom action is the
most flexible approach, and is really the only approach that is supported across all of the SharePoint
development models.
The following example demonstrates how to create a custom action targeting the ScriptLink location as a
CAML element that can be deployed in a SharePoint feature:
ScriptLink Custom Action CAML Element

<CustomAction
Location="ScriptLink"
Sequence="100"
ScriptSrc="~sitecollection/_catalogs/masterpage/scripts/myscript.js" />
<CustomAction
Location="ScriptLink"
Sequence="101"
ScriptBlock="function DoSomething() { };" />
</Elements>
Creating a new custom action requires the following attributes:
 Location. The location property indicates the target control for inserting a custom action. The value of
this property must be specified as ScriptLink.
 Sequence. The sequence number indicates the order in which targeted actions will be loaded into the
control. For the ScriptLink control, this indicates the order in which scripts will be inserted into the
page. A lower number indicates a higher priority.
 ScriptSrc. Contains the URL to a file that contains JavaScript to be added to the page.
 ScriptBlock. Contains the JavaScript block to be added to the page.
The following example demonstrates how to create a custom action targeting the ScriptLink
programmatically using the JavaScript client-side object model from a SharePoint-hosted app:
ScriptLink Custom Action Using JavaScript Client-Side Object Model

var ctx = new SP.ClientContext(appWebUrl);
var factory = new SP.ProxyWebRequestExecutorFactory(appWebUrl);
ctx.set_webRequestExecutorFactory(factory);
var site = new SP.AppContextSite(ctx, hostWebUrl);
var web = ctxSite.get_web();
var newAction = web.get_userCustomActions().add();

newAction.set_location('ScriptLink’)
newAction.set_sequence(110);
newAction.set_scriptSrc(scriptUrl);
newAction.update();
ctx.executeQueryAsync(success,error);
Additional Reading: You can find out more about the ScriptLink class on MSDN at
Demonstration: Deploying a ScriptLink Custom Action

In this demonstration, you will see an example of how to develop and deploy a ScriptLink custom action.
Demonstration Steps
password Pa$$w0rd.
3. On the Windows® Start page, click Computer.
4. In File Explorer, browse to E:\DemoCode\ScriptLinks, and then double-click

Contoso.WebControls.CustomActions.sln.
5. In the How do you want to this this type of file (.sln)? dialog box, click Visual Studio 2012.
6. In Visual Studio®, in Solution Explorer, expand the Contoso.WebControls.CustomActions project

node, expand the Layouts folders, and then expand the Scripts folder.
7. Notice that the jQuery-1.7.1.min.js is being deployed to the SharePoint file system. Note that this
location will allow the file to be accessed by using the virtual path "_layouts".
8. Expand the ScriptLinks folder, and then double-click the Elements.xml file.
9. Review the two custom actions. Note that one custom action is using the ScriptSrc property to insert
a script link tag, and the other is using a ScriptBlock property to insert a snippet of JavaScript.
10. Note that the custom action with the lower sequence number of 150 will be inserted before the
higher sequence number of 151.
11. Expand the Features folder, and then double-click on the ScriptLinks feature.
12. In Feature Designer, note that the Scope is Site.

13. On the DEBUG menu, click Start Without Debugging.
14. Note that the script block has executed when the alert dialog is displayed in Internet Explorer®.
15. In the Message from webpage dialog box, click OK.
17. In Visual Studio, in the Features folder, double-click the ScriptLinks feature.
18. In Feature Designer, in the Scope list, click WebApplication.
19. On the FILE menu, click Save All.

21. Note that the script block is still executed on the site. Explain that the script links will now be inserted
on every site contained in the web application.

24. In Visual Studio, on the BUILD menu, click Retract.
25. Wait for the retractions process to complete, and then close Visual Studio.
Using the JSLink Property with Display Templates

The JSLink property was introduced in SharePoint
2013 and provides a flexible alternative for
developers to customize the display and behavior
of content. The JSLink property allows a developer
to specify a link to a JavaScript file that contains
client-side code to modify the behavior and display
of an object. Customizing objects using JSLink is
supported in Sandbox solutions, and the new
SharePoint 2013 App model. This also means it is
supported in SharePoint Online as part of an Office
365 subscription.
The JSLink property is not a replacement for Page

Field controls, and is not supported when displaying content on publishing page. However, it can be used
to customize the display and edit behavior of publishing columns if a user chooses to utilize the standard
View and Edit Properties forms on Page items.
Using the JSLink Property

The JSLink property can be used to customize fields, but is also available for other objects including:
 Web Parts
o PromotedSitesViewWebPart
o BaseXsltListWebPart
o ListFormWebPart
o TilesViewWebPart
 SPField including most child types that inherit from SPField
 SPContentType
 SPForm
 SPView
The JSLink property can be set programmatically, or it can be specified as part of a CAML element.
The following code sample demonstrates how set the JSLink property on a Field element:
Setting the JSLink Property on a Custom Field CAML Element

<Field
ID="{c3b0d62d-f325-4d08-81f9-29661c73028c}"
Name="ContosoProductCode"
DisplayName="Product Code"
Type="Text"
Required="TRUE"
JSLink="~sitecollection/style library/scripts/templates/ProductCodeFieldTemplate.js"
Group="Contoso Publishing Columns">
</Field>
</Elements>
Building the Template

Building a template involves implementing functions to satisfy three requirements:
 Registration: This function is required to register template overrides with the page template
manager.
 Form Template Overrides: For each object in your template, you can provide custom display
templates for each of the separate forms: View, NewForm, EditForm, and DisplayForm.
 Callbacks: As part of rendering the display template for each form, you can register a selection of
callbacks to be able to response to user actions.
Depending on the specific object being customized, there are additional properties available.
Registering a Template
When specifying the JSLink property, only the name of the file is provided. In order to register the
template, the file must contain an Immediately Invoked Function Expression (IIFE). This function is
executed when the file is loaded.
The following example demonstrates an anonymous function to register a client-side template for a field:
Registering Template Overrides for a Field Object

(function () {
var ProductCodeFieldCtx = {};
ProductCodeFieldCtx.Templates = {};
ProductCodeFieldCtx.Templates.Fields = {
'ContosoProductCode’: {
'View’: renderProductCodeView,
'NewForm’: renderProductCodeNew,
'EditForm’: renderProductCodeEdit,
'DisplayForm’: renderProductCodeDisplay
}
};
SPClientTemplates.TemplateManager.RegisterTemplateOverrides(ProductCodeFieldCtx);
})();
The function is dynamically building up an object that is passed to the

SPClientTemplates.TemplateManager.RegisterTemplateOverrides function. The object supports the
following properties:
 View
 Header
 Body
 Footer
 Group
 Item
 Fields
 OnPreRender
 OnPostRender
It is not required to provide an override for each of these properties, and not all properties are applicable
to all requirements. For example, the Header, Item, and Footer properties can be used when customizing
a template for an SPList or SPView object. The OnPreRender and OnPostRender properties can be used to
call functions before and after a template is rendered.
The Fields property is specified in the format {FieldName : {Scope : Override}}:
 FieldName. The internal field name of the field to override.
 Scope. This defines which forms to override. Choices are View, DisplayForm, NewForm, and EditForm.
 Override: The function to invoke.
Rendering a Template Override

In addition to the normal callbacks you can associate with various DOM components by using JavaScript,
each template override registered with the template manager includes a set of available callbacks you can
use to respond to specific events.
The following code demonstrates how to implement the function to render the override for a field’s
NewForm scope:
Rendering a Template Override

function renderProductCodeNew (fieldCtx) {
var formCtx = SPClientTemplates.Utility.GetFormContextForCurrentField(fieldCtx);

var result = += '<div><input id=' + STSHtmlEncode(formCtx.fieldSchema.Id) + '
type="text"></div>';
return result;
}
The template override function is very similar to the purpose of the Field Control class. Its job is to retrieve
values from the form context containing the field’s values, and render the HTML markup to display in the
browser.
Handling Callbacks
In addition to the normal callbacks you can associate with various DOM components by using JavaScript,
each form template includes a set of available callbacks you can use to respond to specific events related
to the form. The following are two of the most important callbacks that should be handled for the
NewForm and EditForm scopes:
 registerInitCallback. This callback is invoked when the form is being loaded. This is where you can set
the default values for controls displayed on the form.
 registerGetValueCallback. This callback is invoked when the form is being submitted. This is where you
provide the value that will be saved to the SharePoint content item.
There are additional callbacks available, depending on the type of template and the view being
overridden.
The following example demonstrates functions to implement callbacks for registerInitCallback and
registerGetValueCallback:
Registering Template Callback Functions

var formCtx = SPClientTemplates.Utility.GetFormContextForCurrentField(fieldCtx);
formCtx.registerInitCallback(formCtx.fieldName, function() {
var productCodeInput = document.getElementById('productCodeTextBox’);
var productCodeValue = formCtx.fieldValue != null ? formCtx.fieldValue : '';
if ( productCodeInput != null && productCodeValue != null ) {
productCodeInput.value = productCodeValue;
}
});
formCtx.registerGetValueCallback(formCtx.fieldName, function() {
var productCodeInput = document.getElementById('productCodeTextBox’);
if ( productCodeInput != null ) {
return productCodeInput.value;
}
else {
return '';
}
});
Callbacks are registered as part of the function that overrides a particular form scope. To avoid
duplicating code, it is a good idea to place these in a separate function that can be called as needed.
Deploying the Template

Deploying the template is simply a matter of deploying the JavaScript file to the location that it was
referenced in the JSLink property. If you choose to deploy the file to the 15\Templates\Layouts folder, it
can be referenced from any site collection. However, this option is not available in SharePoint Online.
The following example demonstrates deploying the template JavaScript file by using a Module element:
Deploying a JSLink Template File

<Module Name="JSLink" Url="style library/templates">
<File Path="JSLink\PhoneNumberValidator.js" Url="ProductCodeFieldTemplate.js"
Type="GhostableInLibrary" ReplaceContents="TRUE" />
</Module>
</Elements>
Lab: Customizing a SharePoint Publishing Site

Scenario
The Contoso Marketing team would like to author new articles related to product news and events. They
have requested a custom page layout for authoring product articles that includes the related product
code. When users author a product news article, they should be able to edit the product code. When the
product code is displayed on the page, it should be hyperlinked to the product catalog details page.
Objectives
 Build and deploy custom site columns and content types to support publishing pages.
 Build and deploy a custom page field control and rendering templates.
 Build and deploy custom page layouts with page fields and web parts.
Lab Setup
Exercise 1: Building a Custom Page Field Control

Scenario
In this exercise, you will create a custom page field control to support rendering requirements for Contoso
product codes. The field control should ensure that users enter product codes in the correct format, and
display the product code as a hyperlink to the product catalog details page for the related product.
You will start by creating a User Control with rendering templates for display and edit. You will then
create a field control class to utilize the rendering templates.
1. Create Rendering Templates

2. Create a Field Control
 Task 1: Create Rendering Templates


3. Launch Visual Studio 2012 and open the solution at
E:\Labfiles\Starter\Layouts\Contoso.Website.Layouts.sln.
4. Add SharePoint Mapped Folder to TEMPLATES\CONTROLTEMPLATES.

5. Add a new User Control (Farm Solution Only) with the name Contoso.ProductCodeTemplate.
6. Open the Contoso.ProductCodeTemplate.ascx file. In the code editor, append the following code:
<SharePoint:RenderingTemplate ID="ContosoProductCodeRenderingTemplate"
runat="server">
<Template>
<asp:RegularExpressionValidator ID="ProductCodeValidator" runat="server"
ControlToValidate="ProductCodeTextBox"
ErrorMessage="Please enter a valid product code in the format @@@-####."
ValidationExpression="^[A-Z]{3}[0-9]{4}$" />
</Template>
<SharePoint:RenderingTemplate ID="ContosoProductCodeDisplayRenderingTemplate"
runat="server">
<Template>
<asp:HyperLink ID="ProductCodeHyperLink" runat="server" />
</Template>
Note: If you prefer, you can copy this markup from the text file at
E:\Starter\Snippets\RenderingTemplate.txt.
 Task 2: Create a Field Control

1. In Solution Explorer, click the project and add a new Class named ProductCodeField.cs.
2. Open ProductCodeField.cs file, and add the following using statements:
using System.Web.UI.WebControls;
using Microsoft.SharePoint.WebControls;
3. Replace the class stub with the following code:
public class ProductCodeField : BaseFieldControl

{
}
4. Within the class body, add the following code:

protected RegularExpressionValidator ProductCodeValidator;
protected HyperLink ProductCodeHyperLink;
{
}
public override string DisplayTemplateName
{
get { return "ContosoProductCodeDisplayRenderingTemplate"; }
}
{
if ( this.ControlMode == SPControlMode.Display )
{
ProductCodeHyperLink =
(HyperLink)this.TemplateContainer.FindControl("ProductCodeHyperLink");
ProductCodeHyperLink.NavigateUrl =
String.Format("{0}/Products?ProductCode={1}", SPContext.Current.Web.Url,
(string)this.ItemFieldValue);
ProductCodeHyperLink.Text = (string)this.ItemFieldValue;
}
else
{
ProductCodeTextBox =
(TextBox)this.TemplateContainer.FindControl("ProductCodeTextBox");
ProductCodeValidator =
(RegularExpressionValidator)this.TemplateContainer.FindControl("ProductCodeValidator"
);
}
}
{
get
{
}
set
{
ProductCodeTextBox.Text = (string)this.ItemFieldValue;
}
}
Note: If you prefer, you can copy this code from the text file at
E:\Starter\Snippets\ProductFieldCode.txt.
Results: After completing this exercise, you should have created a User Control containing rendering
templates, and a custom field control.
Exercise 2: Building a Page Layout

Scenario
In this exercise, you will complete a custom page layout that will be used by Contoso Marketing to author
publishing articles pages related to products.
You will start by adding page field controls, including the custom ProductCodeField control you created
in the previous exercise. Next, you will add a web part zone to enable users to add web parts to pages
using the SharePoint UI. Then you will embed a Script Web Part directly into the layout. Finally, you will
deploy and test the page layout.
1. Add Content Controls to a Page Layout
2. Deploy and Test the Page Layout
 Task 1: Add Content Controls to a Page Layout

1. In Solution Explorer, expand the PageLayouts folder, then expand the ProductArticleLayout folder,
and then double-click the ProductArticleLayout.aspx file.
2. In the code editor, append the following code:
<%@ Register Tagprefix="ContosoWebControls"

Namespace="Contoso.Website.Layouts.FieldControls" Assembly="Contoso.Website.Layouts,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=8dec8fdacbd4988c" %>
3. In the code editor, add a content placeholder by appending the following code:
<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">

<PublishingWebControls:EditModePanel ID="EditModePanel" runat="server"
CssClass="edit-mode-panel title-edit">
<SharePointWebControls:TextField ID="TitleField" runat="server"
FieldName="Title"/>
</PublishingWebControls:EditModePanel>
<ContosoWebControls:ProductCodeField
ID="ProductCodeField"FieldName="ContosoProductCode"
runat="server"></ContosoWebControls:ProductCodeField>
<PublishingWebControls:RichHtmlField ID="PageContentField"
FieldName="PublishingPageContent" HasInitialFocus="True" MinimumEditHeight="400px"
runat="server"/>
<WebPartPages:WebPartZone ID="Full " Title="Full" runat="server">
<ZoneTemplate></ZoneTemplate> </WebPartPages:WebPartZone>
4. Save all changes to the project and Deploy.
 Task 2: Deploy and Test the Page Layout

1. From Internet Explorer, browse to http://www.contoso.com. Sign In if necessary.
2. From Site contents, open the Pages app.

3. Create a new page named "My Product Article" and select the "(Product Article Page) Product
Article" page layout.
4. Verify that the Product Code RegEx validation is working properly.

5. Validate that you can Add a Web Part to the Web Part Zone.
6. Publish the page.
7. Validate that the Product Code is being displayed as the correct URL.
Results: After completing this lab, you will have learned how to build and deploy page layouts that
include page field controls and web parts.

In this module you learned how to work with publishing sites programmatically by using the publishing
API, and how to use and customize page content controls. You now have the skills to:
 Build solutions that customize publishing settings through code.
 Develop custom content controls to support web content solutions.
 Add content controls such as field controls and web parts to page layouts.
Provision publishing artifacts, including Page Layouts and Publishing Pages.
Review Question(s)
Test Your Knowledge

Question
Which of the following objects does not support the JSLink Property? (Select one)
SPField
SPView
BaseFieldControl
SPContentType
ListFormWebPart
Statement Answer
Can Publishing Page Layouts or Pages be

provisioned from a SharePoint App by using a
Schema Element?
Question: What is the purpose of the EditModePanel control in a Page Layout?

Statement Answer
Are Delegate controls supported in SharePoint

Apps?
Question: Compare and contrast the Solution and Features Framework versus the Apps for
SharePoint model. What are some of the limitations in the Apps for SharePoint model that
specifically related to Web Content Management.
7-1
Module 7
Structuring and Publishing Websites for All Users
Contents:
Module Overview 7-1
Lesson 1: Website Structure and Navigation 7-2
Lesson 2: Publishing Content 7-11
Lab A: Structuring a SharePoint Publishing Site 7-17
Lesson 3: Publishing to Mobile Devices 7-23
Lesson 4: Multi-Language Sites Using Variations 7-27
Lab B: Publishing Sites for Multiple Devices 7-33

Module Overview
This module will focus on providing you with the knowledge to build websites that are mobile device
friendly, support multiple languages, and employ proper navigation. This will be accomplished by
introducing you to device channels, managed navigation, variations, and other Microsoft® SharePoint®
2013 features.
Objectives
 Configure website structure and navigation.
 Understand the differences between structured and metadata navigation.
 Configure site navigation programmatically.
 Utilize the basic publishing features of SharePoint 2013.
 Use the new cross-site publishing features of SharePoint 2013.
 Work with mobile devices by using Device Channels.
 Configure and implement variations for multilingual sites.
 Work with human- and machine-translation tasks in variation sites.

7-2 Structuring and Publishing Websites for All Users
Lesson 1
Website Structure and Navigation
This lesson will introduce you to the various ways that SharePoint implements navigation. This includes
reviewing each of the areas that utilize SharePoint navigation providers and how you can customize them.
You will learn how to configure navigation by using both structured and managed navigation features. In
addition, you will learn how to re-use navigation terms by pinning them to other site collections’
navigation term sets.
Lesson Objectives
 Describe how SharePoint implements navigation.
 Configure site collection navigation.
 Work with the new managed navigation features.

 Configure navigation programmatically.
Typical User Navigation

Every successful website must have some type of
navigation that guides users through the various
areas of content. There are several ways that this
can be accomplished, including menus, tree views,
and breadcrumbs. The goal of these controls is to
make it easy for a user to browse the content with
the fewest possible clicks, and without having to
remember the URLs of the items. There are,
however, individuals who do not utilize the
navigation of a site and who prefer to navigate by
using bookmarks or by simply remembering URLs.
In previous versions of SharePoint, URLs tended to
be rather complex and not user friendly. In SharePoint 2013, URLs are friendlier and enable users to
remember a path to a particular item, rather than having to browse to it by using navigation elements or
bookmarks.
Types of Navigation
When designing your navigation strategy, you should take into consideration all of your web applications,
site collections, and sites. You should also consider links to sites outside of SharePoint. When you consider
these types of links, you will find that there are three types of navigation that you can present to a user in
your SharePoint sites:
 Global Navigation. This enables users to navigate within a site collection, including the sites in the site
collection.
 Local Navigation. This enables users to navigate within a site. Items could include lists and pages
within the site. This traditionally has been implemented via the Quick Launch area in SharePoint.
 Breadcrumb Navigation. This control enables users to navigate to any site between the top site and
your current site.
Navigation Providers
The nodes that make up a navigation menu must be stored somewhere. This can be in a SharePoint list, a
database, an XML file, or some other storage mechanism. To use this data, you must create or use an out-
of-the-box navigation provider. There are several providers that come with SharePoint, including:
 SPSiteMapProvider
 SPContentMapProvider
 SPXmlContentMapProvider
 SPNavigationProvider
 PortalSiteMapProvider
 TaxonomySiteMapProvider
If you want to utilize data that exists outside of SharePoint for your navigation, you must create and then
register a navigation provider with SharePoint. Registration is simple and is performed by adding the
navigation provider to the web.config file of the targeted web application.
Navigation Areas
SharePoint 2013 includes two main areas of navigation: the Global Navigation at the top of a site page,
and the Current Navigation area on the left side of a page. Each of these areas is fully customizable, or
natively supports dynamic generation of menu items. If you want to override how a navigation menu gets
its navigation nodes, you can simply override the SharePoint DelegateControl in which the data source is
defined.
Global navigation is defined in the AjaxDelta DeltaTopNavigation control of the basic master page. You
can override the data source by overriding the TopNavigationDataSource delegate control:
SharePoint Top Navigation Menu

<SharePoint:AjaxDelta id="DeltaTopNavigation" BlockElement="true" CssClass="ms-
displayInline ms-core-navigation" role="navigation" runat="server">
<SharePoint:DelegateControl runat="server" ControlId="TopNavigationDataSource"
Id="topNavigationDelegate">
<Template_Controls>
<asp:SiteMapDataSource
ShowStartingNode="False"
SiteMapProvider="SPNavigationProvider"
id="topSiteMap"
runat="server"
StartingNodeUrl="sid:1002"/>
</Template_Controls>
<asp:ContentPlaceHolder id="PlaceHolderTopNavBar" runat="server">
<SharePoint:AspMenu
ID="TopNavigationMenu"
Runat="server"
EnableViewState="false"
DataSourceID="topSiteMap"
AccessKey="<%$Resources:wss,navigation_accesskey%>"
UseSimpleRendering="true"
UseSeparateCss="false"
Orientation="Horizontal"
StaticDisplayLevels="2"
AdjustForShowStartingNode="true"
MaximumDynamicDisplayLevels="2"
SkipLinkText="" />
</asp:ContentPlaceHolder>
</SharePoint:AjaxDelta>
The Quick Launch navigation area is provided in SharePoint master pages by the SPNavigationManager
control with an ID of QuickLaunchNavigationManager. Notice that you can override the data source by
overriding the QuickLaunchDataSource delegate control:
Example of the Quick Launch Markup in a Basic SharePoint Master Page

<SharePoint:SPNavigationManager
id="QuickLaunchNavigationManager"
runat="server"
QuickLaunchControlId="V4QuickLaunchMenu"
ContainedControl="QuickLaunch"
EnableViewState="false"
>
<SharePoint:DelegateControl runat="server"
ControlId="QuickLaunchDataSource">
<Template_Controls>
<asp:SiteMapDataSource
SiteMapProvider="SPNavigationProvider" ShowStartingNode="False" id="QuickLaunchSiteMap"
StartingNodeUrl="sid:1025" runat="server" />
<SharePoint:AspMenu id="V4QuickLaunchMenu"
runat="server" EnableViewState="false" DataSourceId="QuickLaunchSiteMap"
UseSimpleRendering="true" Orientation="Vertical" StaticDisplayLevels="3"
AdjustForShowStartingNode="true" MaximumDynamicDisplayLevels="0" SkipLinkText="" />
</SharePoint:SPNavigationManager>
<SharePoint:SPNavigationManager
id="TreeViewNavigationManagerV4"
runat="server"
ContainedControl="TreeView"
CssClass="ms-tv-box"
>
<SharePoint:SPLinkButton runat="server"
NavigateUrl="~site/_layouts/15/viewlsts.aspx" id="idNavLinkSiteHierarchyV4"
Text="<%$Resources:wss,treeview_header%>"
accesskey="<%$Resources:wss,quiklnch_allcontent_AK%>"
CssClass="ms-tv-header" />
<SharePoint:DelegateControl
runat="server" ControlId="TreeViewAndDataSource">
<Template_Controls>
<SharePoint:SPHierarchyDataSourceControl
runat="server"
id="TreeViewDataSourceV4"
RootContextObject="Web"
IncludeDiscussionFolders="true"
/>
<SharePoint:SPRememberScroll
runat="server" id="TreeViewRememberScrollV4"
onscroll="javascript:_spRecordScrollPositions(this);"
style="overflow:
auto;">
<SharePoint:SPTreeView
id="WebTreeViewV4"
runat="server"
ShowLines="false"
DataSourceId="TreeViewDataSourceV4"
ExpandDepth="0"
SelectedNodeStyle-
CssClass="ms-tv-selected"
NodeStyle-CssClass="ms-
tv-item"
SkipLinkText=""
NodeIndent="12"
ExpandImageUrl="/_layouts/15/images/tvclosed.png?rev=23"
ExpandImageUrlRtl="/_layouts/15/images/tvclosedrtl.png?rev=23"
CollapseImageUrl="/_layouts/15/images/tvopen.png?rev=23"
CollapseImageUrlRtl="/_layouts/15/images/tvopenrtl.png?rev=23"
NoExpandImageUrl="/_layouts/15/images/tvblank.gif?rev=23"
>
</SharePoint:SPTreeView>
</SharePoint:SPRememberScroll>
</SharePoint:SPNavigationManager>
SharePoint enables a breadcrumb control that does not exist by default on the master pages:
Example of HTML Markup to Implement the Breadcrumb Control

<div class="SolidBreadCrumb s4-notdlg">
<asp:SiteMapPath ID="SiteMapPath1" runat="server"
SiteMapProviders="SPSiteMapProvider,SPXmlContentMapProvider"
RenderCurrentNodeAsLink="false" NodeStyle-CssClass="SolidBreadCrumb"
CurrentNodeStyle-CssClass="SolidBreadCrumbCurrent" RootNodeStyle-
CssClass="SolidBreadCrumbRoot" HideInteriorRootNodes="true"
SkipLinkText=""/>
</div>
Structured Navigation
Structured navigation in SharePoint builds
navigation menus based on the sites and pages in
the site collection. When configuring structured
navigation, you can select whether sites and\or
pages are displayed automatically. You also have
the ability to specify how many items will be
displayed in the navigation area. By default, this is
limited to 20 items. It is poor practice to have more
than a handful of items in the navigation areas;
limiting the items is recommended.
When you configure SharePoint sites to use

structured navigation, a new node is added to the
navigation nodes each time a new site is created. You can also customize the navigation nodes by
manually adding items.
The default provider used in structured navigation is the SPNavigationProvider. This provider will
interrogate the node data this is stored in the SPWeb’s Navigation property. These nodes are added
automatically when various events occur in SharePoint (like a new site being added). When adding new
nodes, you may not see your changes displayed immediately because the nodes are cached in a special
memory object called CachedNavigation of the SPWeb object.
Navigation Security Trimming

Only items that SharePoint has added get security trimmed. This is because a security scope will be added
to the navigation node properties by SharePoint. Any manual links you add will always display for every
user because SharePoint will not know what security scope to apply to those nodes.
Farm-Wide Navigation
Structural navigation only spans a site collection. It does not allow you to have a single instance of
navigation that can be used to provide the same links across all of your SharePoint sites in the farm. In
order to do this, you would need to implement your own custom navigation provider and point your
master pages to this navigation provider. It also means that you will need to design your master pages to
allow for both a global-global navigation area and a global-local navigation area. If you choose not to
implement a farm-wide navigation strategy, you will be limited to site collection navigation as your global
navigation strategy.
Global Navigation
Global navigation with structured navigation will display only items that exist in the site collection. You
must manually add any nodes you want to display that live outside of the respective site collection. This
means that you would also need to add these nodes manually to any other site collection’s structural
navigation configuration. You will not be able to reuse your settings.
Current Navigation
With current navigation in a structured navigation configuration, by default you will see all the items at
the current site level. This is helpful for navigating inside the respective site. However, this can be
overridden to display exactly what would be displayed in the global navigation, and you also have the
ability to customize the navigation nodes.
Managed Navigation
In addition to structural navigation, SharePoint
2013 has added a new option called Managed
Navigation. Managed navigation uses the Managed
Metadata service application to feed navigation
nodes via a special navigation provider called
TaxonomySiteMapProvider. To add navigation to
a site, you simply add terms to a term set. Each
term has a set of properties that define the title and
the URL of the node.
Navigation Term Sets

Each term set can be used only once per site
collection. If you attempt to use the same
navigation term set in multiple site collections, the last one to be configured will use the navigation, any
previous site collections will display an error when rendered. Each term set must be set with the
_Sys_Nav_IsNavigtainoTermSet custom property in order for it to be used as a navigation term set.
Term Sets that are created programmatically must include specific custom properties in order to be used
as managed navigation:
Create a Term Set for Use as Managed Navigation

//create term set
termSet = group.CreateTermSet(name);
termSet.Description = name;
termSet.IsAvailableForTagging = true;
termSet.IsOpenForTermCreation = true;
//set properties
termSet.SetCustomProperty("_Sys_Nav_IsNavigationTermSet", "True");
//termSet.SetCustomProperty("_Sys_Facet_IsFacetedTermSet", "False");
//termSet.SetCustomProperty("_Sys_Nav_AttachedWeb_SiteId", site.ID.ToString());
//termSet.SetCustomProperty("_Sys_Nav_AttachedWeb_WebId", site.RootWeb.ID.ToString());
//termSet.SetCustomProperty("_Sys_Nav_AttachedWeb_OriginalUrl", site.RootWeb.Url);
Navigation Terms
Terms that are added to a navigation term set must also be set up with custom properties in order for
them to be used. If these properties are added or configured incorrectly, the navigation menus will display
errors and the UI can become unresponsive when editing the terms. There are two types of navigation
links that can be used:
 Target URLs. These use the _Sys_Nav_TargetUrl property and must be set to a valid page in the site. If
the page does not exist in the site, the node will not render.
 Simple Link URLs. These use the _Sys_Nav_SimpleLinkUrl property and are absolute URLs to a valid
web site (both inside and outside of SharePoint).
Creating navigation terms programmatically requires special properties:
How to Create Navigation Terms

Term t = termSet.CreateTerm("Home", 1033);
t.SetLocalCustomProperty("_Sys_Nav_TargetUrl", "/Pages/Home.aspx");
t = termSet.CreateTerm("Intranet", 1033);
t.SetLocalCustomProperty("_Sys_Nav_SimpleLinkUrl",
"http://intranet.contoso.com/Pages/Home.aspx");
Note: Terms do not have versioning features like pages. If you change a term, the change
is immediate and you cannot revert to previous changes.
Sort Order
Just like with structured navigation, you also have the ability to sort the terms in some custom fashion via
the Term Store Management Tool. Using a custom sort order will ensure that terms appear in a consistent
manner, regardless of the language or any changes in the default labels.
Reusing Managed Navigation Terms

Managed navigation term sets can be used only on one site collection at a time. As a result, if you want
consistent navigation across all site collections, you will need to create a second term set with the same
items. Luckily, SharePoint’s managed metadata service enables you to pin terms to other term sets. This is
like creating a pointer to other terms and making them display as if they existed in the term set. You can
pin a term to another term set by using the ReuseTermWithPinning method of a TermSet object.
Note: When you reuse terms that are relative links, the code will check to see if the page
actually exists in the site. If it does not, then the node will not be rendered in the navigation area.
You can use pinning to create pointers to terms from other term sets:
How to Pin a Term to Another Term Set

static void PinTermSet(TermSet source, TermSet target)
{
foreach (Term t in source.Terms)
{
target.ReuseTermWithPinning(t);
}
}
Friendly URLs
Previous versions of SharePoint had an interesting way of generating the item’s URL. The links were
awkward because they tended to be incredibly long and not easy to remember. These long URLs also
meant that when you copied and pasted them in emails, they would take up much of the email body. It
also meant that when a search engine indexed the path of the items, it would not be able to do any type
of path-based relationships.
An example of an unfriendly URL for users and search engines from previous SharePoint versions is:
http://www.contoso.com/SitePages/Publishing/Product.aspx?ID=157
A more friendly version of this URL in SharePoint 2013 would be:
http://www.contoso.com/Product/157
Shorter URLs are made possible by the managed navigation feature of SharePoint 2013. You can create
term-driven navigation that will simplify your URLs. For example, you can convert the following URL from
http://intranet.contoso.com/Pages/home.aspx to http://intranet.contoso.com/Home.
Friendly URLs even let you assign more than one term to a page, so the above example could also have a
term-drive page called http://intranet.contoso.com/Default. These friendly URLs assist with Search Engine
Optimization (SEO) on Internet-facing sites.
Discussion: Navigation Scenarios

Publishing and Taxonomy Classes

Each SharePoint site is represented by the SPWeb
class. The SPWeb class has a property called
Navigation that is of type SPNavigation.
SPNavigation has four properties of type
SPNavigationNodeCollection:
 GlobalNodes
 TopNavigationBar
 QuickLaunch
 SearchNav
Each collection contains zero or more

SPNavigationNode objects. These objects contain several properties that determine how the node will
be displayed. You can utilize Windows® PowerShell to interrogate the navigation nodes. An example of a
navigation node and its properties is:
Title : Contoso Teams
TitleResource : Microsoft.SharePoint.SPUserResource
IsVisible : True
IsDocLib : True
IsExternal : False
Id : 1000
ParentId :0
Parent :
Navigation : Microsoft.SharePoint.Navigation.SPNavigation
Url : /default.aspx
LastModified : 6/25/2013 2:16:41 AM
Children : {}
Properties : {vti_globalpage}
TargetSecurityScopeId : 6fba9156-d2b1-4a9f-a127-7f05a55f2020
TargetParentObjectType : Web
As you can see, the node contains some very important properties that determine how the node will be
displayed, what type of node it is, and what kind of permissions will be enforced on the node.
The following code shows a simple example of how to add navigation nodes programmatically in a non-
publishing SharePoint site:
Adding Navigation Nodes in a Non-Publishing Site

{
{
SPNavigationNode node = new SPNavigationNode("Microsoft",
"http://www.microsoft.com");
web.Navigation.GlobalNodes.AddAsFirst(node);
web.Navigation.QuickLaunch.AddAsFirst(node);
}
}
As you can see from the code snippet above, there are no configuration properties available that enable
you change the navigation from Structured to Metadata Navigation. This has to be done by using a
special class called WebNavigationSettings.
You can manage site navigation programmatically by using server-side and client-side APIs. Each type of
navigation requires a different set of classes in order to manipulate it.
Publishing webs require a different approach to updating navigation than non-publishing sites:
Adding Navigation Nodes to a Publishing Site

{
{
SPNavigationNode node = new SPNavigationNode("Microsoft",
"http://www.microsoft.com");
pubWeb.Navigation.CurrentNavigationNodes.AddAsFirst(node);
pubWeb.Navigation.GlobalNavigationNodes.AddAsFirst(node);
}
}
Changing the type of navigation provider is implemented in a new class in SharePoint 2013. Older classes
do not know about metadata navigation:
Setting the Navigation to Metadata Navigation
WebNavigationSettings = new WebNavigationSettings(web);

webNavigationSettings.ResetToDefaults();
webNavigationSettings.GlobalNavigation.Source =
StandardNavigationSource.TaxonomyProvider;
webNavigationSettings.GlobalNavigation.TermStoreId = termSet.TermStoreId;
webNavigationSettings.GlobalNavigation.TermSetId = termSet.Id;
webNavigationSettings.CurrentNavigation.Source =
StandardNavigationSource.TaxonomyProvider;
webNavigationSettings.CurrentNavigation.TermStoreId = termSet.TermStoreId;
webNavigationSettings.CurrentNavigation.TermSetId = termSet.Id;
webNavigationSettings.Update(taxonomySession);
TaxonomyNavigation.FlushSiteFromCache(web.Site);
Lesson 2
Publishing Content
In this lesson, you will learn about the basic web publishing features of SharePoint, which include check-
in, check-out, content approval, versioning, and workflows. Next, you will explore the new features of
cross-site publishing in SharePoint 2013, and how to set up and configure lists and libraries to be catalogs
that are used to generate cross-site source and target sites. Finally, you will be shown that search and
metadata navigation are a big part of the cross-site publishing architecture.
Lesson Objectives
 Describe the publishing features of SharePoint.
 Set up web authoring environments.
 Describe the components needed to configure cross-site publishing.

 Configure lists as catalogs.
 Set up catalogs connections.
 Describe how cross-site navigation works with managed metadata.
Publishing Features
Companies today are becoming very agile. Content
must be published in larger quantities and at a
faster pace. Anything that can help automate and
increase productivity will help to deliver high-
quality content to users who need and want it. You
can easily achieve these publishing goals by
leveraging the publishing features in SharePoint.
There are several ways to use SharePoint for

publishing. One very common pattern is to host
your Internet and intranet site. In the case of the
Internet site, the content represents the company
and its brand. Protecting a company’s brand is very
important, so content published to the site should be approved by the proper managers, which at a
minimum will include the marketing and legal departments.
SharePoint provides several publishing features to support these types of content and the policies and
procedures that wrap them. These include:
 Check in and Check out. This feature enables a user to check out content that is being edited, which
prevents other authors from making changes.
 Major and Minor versions. This feature enables users to keep older versions of files, with optional
comments. This helps to prevent losing old work due to copy-and-replace actions.
 Content Approval. When enabled, only content that has a status of Approved will display to users. Any
draft, pending, or rejected versions will not be displayed.
 Approval Workflows. If you have pages or content that must be approved by a single or by multiple
users, you can set up a workflow that requires those individuals’ approval.
Content Approval Workflows

SharePoint 2013 provides some very simple content approval workflow templates to help with the
content approval process. These workflows assign tasks to individuals when a piece of content is
published. Each individual in the approval process will need to approve the item; once the workflow is
completed, the status of the item is updated to Approved. It is also possible for the approvers to reject an
item.
When simply assigning tasks to approvers will not meet your content approval requirements, you can use
SharePoint Designer to implement much more advanced approval workflows. For example, you can build
workflows that:
 Route approvals based on the type of content (invoices, web page, IT requests, and so forth).
 Route approvals based on metadata (amount of an invoice, the type of IT request, and so forth).
Publishing Environments
In well-organized organizations, you will find a very
specific set of procedures when deploying new
code and customizations to applications. These
procedures normally define a process in which
customizations are moved from one environment
to the next, and each environment is managed by
individuals with specific roles in the deployment
process. For example, when developing a piece of
code, it is common for a developer to work on their
development machine, and when they are code
complete, they will pass the application to the
Quality Assurance (QA) team for testing. In a
traditional organization you will find the following environments:
 Development. The environment in which developers design and build applications that will eventually
be used in production.
 Quality Assurance (QA). A team of engineers that tests the developer’s code to confirm that all
requirements have been met. If requirements have not been met, QA passes the code back to the
developers
 Staging. The environment where the proposed deployment can be tested before going to production.
Any inaccuracies in the deployment process must be documented. If failure occurs, the deployment is
passed back to QA and development for refinement
 Production. The environment for all tested and approved applications and updates.
These well-defined environments ensure that a high quality product is released to users with minimal to
zero issues. In large organizations with large investments in SharePoint, you will find very strict policies
driving the use of all four of these environments.
SharePoint Authoring
In a SharePoint publishing environment, you typically have an additional environment called the
authoring environment. This environment is where users develop the content that will be published to the
production site. The reason for this extra environment is the policy that dictates that no changes will be
made in production without first being approved. These policies prevent any type of editing in the
production environment. As a result, an authoring environment is required. In the absence of these
policies, corporations will edit documents in the production environment, which is also a supported
method of authoring in SharePoint.
Content Deployment APIs

Once an author has built content and had it approved, they need a way to move the content from the
authoring environment to the production environment. This is achieved through Content Deployment
APIs. Content deployment will export the content to a file or directory-based package that can then be
copied to the target production environment, and then deployed by using the import features of the
content deployment API.
Cross-Site Publishing
In addition to the content deployment APIs, there is
a new way of deploying content to sites in
SharePoint 2013 called Cross-site publishing. Cross-
site publishing does not use the content
deployment APIs, but instead utilizes search and
managed navigation as its deployment
methodology. This type of publishing provides
benefits such as:
 Separates content from the branding and

rendering aspects of publishing.
 Spans site collections, web applications, and

farms.
 Mixes authored pages and list content.

Cross site publishing components include:
 Authoring site. The source of content that should be published. This site contains list data that will be
consumed by other sites.
 Catalog list. Source of content that should be published and displayed on a target publishing site.
 Search. The component responsible for finding, indexing, and exposing content to the target
publishing sites.
 Term store. Contains the metadata used to organize the content and the navigation to content in a
publishing site.
 Publishing site. The site that users will use to browse the content authored on the authoring site by
using specific catalog page layouts.
Cross-site publishing can be used to deploy content from one site to one site (1:1) or one site to many
sites (1:N). In order to utilize cross-site publishing you must perform several steps:
1. Enable the Cross-Site Collection Publishing feature on the source site.
2. Configure publishing lists as catalogs.
3. Index your publishing lists.
4. Configure the consumption of the content from the target sites.
Note: As of this writing, SharePoint Online does not support cross-site publishing. Only on-
premise installations can utilize this feature.
Content Deployment Versus Cross-Site Publishing

The Content Deployment API uses various classes in the Microsoft.SharePoint.Deployment namespace.
These APIs will export a set of content into a package, and then that package is imported into the target
site. This can be done both manually and via an automated process using content deployment paths and
jobs from SharePoint Central Administration. This methodology has limitations, including a time lag time
for the job to complete, and the requirement that the source and the target use the same template,
among others.
In comparison, cross-site publishing utilizes classes in the Microsoft.SharePoint.Publishing namespace,

specifically the PublishingCatalogUtility and CatalogCollectionManager classes. These classes utilize
search to find catalogs and can also be used to specify lists that should be set up as catalogs. This is done
by placing a custom property called IsPublishingCatalog on the root folder of the SPList object. Search
will then see this special property and tag it as such in the crawled properties of the list index entry.
The helpful methods in the PublishingCatalogUtility class include:
 GetPublishingCatalogs. Gets all the lists that are setup as catalogs.

 PublishCatalog. Sets the IsPublishingCatalog property on a list.
 UnPublishCatalog. Removes the IsPublishingCatalog property on a list.
Helpful methods in the CatalogCollectionManager include:
 AddCatalogConnection. Add a connection to a catalog in a specific site.
Considerations
There are several moving pieces to cross-site publishing and you should make sure you are aware of any
limitations or quirks before you implement, some of these are:
 Content is not shown until it is indexed. Be sure that your search architecture is configured properly
and is set up to index your content in an efficient manner for publishing the latest content to the
sites. Items will not be indexed if they are not approved, so make that your content is approved.
 Term store does not support versioning. If you create terms that do not have corresponding content,
users will be presented with empty options and the experience will not be optimal
 Basic Lists do not have content approval enabled by default. This means that the list data will always be
indexed and displayed. You will not have the ability to limit the publishing of the content, and it will
be displayed regardless of whether it is complete, valid, or approved.
Product Catalog Site

SharePoint 2013 includes a new site definition called the Product Catalog. It includes several lists and
activate features that support cross-site publishing. You can use this site definition as a starting point for
learning how to use cross-site publishing features.
Catalogs and Catalog Connections

Before content in the libraries and lists can be re-
used across publishing site collections, you have to
share libraries and lists for use as catalogs. When
you share a library or list as a catalog, you specify
that you want to share it with other sites and site
collections. You can also choose to enable
anonymous access to the content in the catalog.
You can also select up to five fields that are used to
uniquely identify items in the catalog. Finally, you
specify a single managed metadata field that is
used as a navigation term set in the publishing site
collections. After a library or list is shared as a
catalog, and the content has been crawled and indexed, you can connect to it from a publishing site
collection.
Consuming Catalogs
Before you can show content from an authoring site collection, you have to configure the catalog
connections in the publishing site collection that will consume those catalogs. When you configure
catalog connections, you specify which catalogs the publishing site collection will use to show content.
When you configure a catalog connection, you must specify several pieces of information, including:
 Whether to integrate catalog content into the site.
 Where to put the categories to use for navigation.

 The term set used for tagging.
 How category item URLs should be constructed..
Category Pages and Catalog Item Pages

By default, SharePoint Server 2013 will automatically create one category page layout and one catalog
item page layout per catalog connection. Pages based on these layouts are created in the Pages library of
a publishing site when you connect the site to a catalog.
By default, a page based on the category page layout is added to the Pages library with the name
Category-<catalog name>. The page is applied to all levels, except the last (catalog item), within the
catalog navigation structure. For example, in an Internet business scenario where you connect to a list of
electronic products, the default category page is applied to all terms within the term set that is used for
catalog navigation. The association between a category page and a term is shown in the Term Store
Management Tool, on the TERM-DRIVEN PAGES tab. The category page layout has the following features:
 The category page layout has four Web Part zones: Body, Left, Bottom Center, and Right.
 A Content Search Web Part is added to the Body Web Part zone.
 The query in the Content Search Web Part is pre-configured to use the result source that is created
automatically during catalog connection. The result source limits search results to the current and
sub-page navigation terms.
 The item display template that is used is Picture on top, three lines on bottom (known as
Item_Picture3Lines in the Master Page Gallery).
By default, a page based on the catalog item page layout is added to the Pages library with the name
CatalogItem-<catalog name>. The page is applied to the last level (catalog item) within the catalog
navigation structure, for example, to show the individual product Contoso Digital Camera M200. The
association between a catalog item page and items within the catalog appears in the Term Store
Management Tool, on the TERM-DRIVEN PAGES tab. The catalog item page layout has the following
features:
 The catalog item page layout has one Web Part zone, which is Body.
 A Catalog-Item Reuse Web Part is added to the Body Web Part zone.
 The query in the Catalog-Item Reuse Web Part is pre-configured to use the result source that was
created automatically during catalog connection, and to limit search results based on an additional
query filter.
In addition to the Catalog-Item Reuse Web Part in the Body Web Part zone, one server-side Catalog-Item
Reuse Web Part is added to the catalog item page layout for each indexed field in the catalog. By default,
all Catalog-Item Reuse Web Parts on a page use the same query as the first Catalog-Item Reuse Web Part.
These fields render server-side in the page layout, and can only be changed by editing the catalog item
page layout directly. Because these are server-side Web Parts, you should edit the HTML source page to
specify the HTML that is rendered together with the catalog content.
Cross-Site Publishing Navigation

As you have already learned, there is a new way to
build navigation in your SharePoint publishing sites
called managed navigation. In addition to
supporting your custom navigation needs,
managed navigation is also used to supplement
cross-site publishing. To organize the content on
the authoring site, a managed metadata site
column is used to categorize the articles by type.
These tagging terms are used on the publishing
side to build up a navigation structure that is used
to pull the article data as part of the search query.
As part of creating a catalog connection, you must
select some metadata on the list that categorizes the content that will be displayed. In addition to
creating the page layouts to support the search web parts to display catalog content, the connection
process will also create the managed navigation terms and map them automatically to the various
categories and products. As you can see, cross-site publishing provides an incredibly powerful way to
auto-generate site content and navigation.
Lab A: Structuring a SharePoint Publishing Site

Scenario
Contoso managers have decided that structural navigation will not meet users’ navigation needs on the
intranet site, and they would like to set up managed navigation. They would like to have some of the
more common corporate external links at the top of the page, in addition to links that reside in the
SharePoint intranet. They would also like these links to be displayed on the various team sites. They have
tasked you with writing some code that will allow them to add navigation programmatically and in a
reliable and replicable manner.
Objectives
 Describe managed metadata navigation.
 Create navigation term sets.
 Configure navigation terms.

 Configure sites to use managed metadata navigation.
 Pin navigation terms to other navigation term sets.
Lab Setup
Exercise 1: Creating a Navigation Term Set

Scenario
In this exercise, you will create code that will set up managed navigation on a publishing site and add
navigation terms to a navigation term set. You will then pin the same terms to another navigation term
set.
1. Create a New Navigation Term Set
2. Add Navigation Terms
3. Pinning Terms to Navigation Term Sets
4. Configure and Test Managed Navigation
 Task 1: Create a New Navigation Term Set

3. Open Internet Explorer and browse to http://intranet.contoso.com.

4. Review the navigation settings for the SharePoint site. Notice that both the global navigation and the
current navigation are set to use structural rather than managed navigation.
6. Open the Central Administration website and browse to the Managed Metadata term store. Notice
that there is currently no navigation term group.
7. Open the solution at E:\Labfiles\Starter\CreateNavigation.sln in Microsoft Visual Studio® 2012.
8. In the CreateNavigation project, add assembly references to the following assemblies:
o Microsoft.SharePoint.Taxonomy.dll
o Microsoft.SharePoint.dll
o Microsoft.SharePoint.Publishing.dll
Note: You can find all of these assemblies in the C:\Program Files\Common
Files\microsoft shared\Web Server Extensions\15\ISAPI folder.
9. In the Program class, add using statements for the following namespaces:
o Microsoft.SharePoint.Administration
o Microsoft.SharePoint.Navigation
o Microsoft.SharePoint.Publishing
o Microsoft.SharePoint.Publishing.Navigation
10. Add a static method named CreateGroup to the Program class. The method should:
o Accept an argument of type TermStore named termStore.
o Accept an argument of type String named name.
o Return an object of type Group.
11. In the CreateGroup method, check whether the passed-in TermStore already contains a Group
object with the passed-in name. If it does not, create the Group object and return it to the caller. If
the Group object already exists, return the existing Group object to the caller.
Note: If you prefer, you can copy the CreateGroup method from the text file at
E:\Labfiles\Starter\Snippets\CreateGroup.txt.
12. Add a static method named CreateNavigationTermSet to the class. The method should:
o Accept an argument of type Group named group.
o Accept an argument of type String named name.
o Return void.
13. In the CreateNavigationTermSet method, check whether the passed-in group already contains a
term set with the passed-in name. If the term set does not already exist:
a. Create the term set.

b. Set a description for the term set.
c. Indicate that the term set is available for tagging.
d. Indicate that the term set is open for term creation.
e. Set a custom property to indicate that the term set is a navigation term set.
f. Commit your changes to the term store.
Note: If you prefer, you can copy the CreateNavigationTermSet method from the text file
at E:\Labfiles\Starter\Snippets\CreateNavigationTermSet.txt.
14. In the Main method, create a new TaxonomySession object using the site collection at
http://intranet.contoso.com.
15. Retrieve the TermStore instance named Managed Metadata Service.
16. Use the CreateGroup method to create a group named Navigation.
17. Use the CreateNavigationTermSet method to create a term set named Intranet.
18. Build the solution, and then start debugging.
19. When the program has finished running and the console window has closed, switch back to the
Central Administration website and reload the Term Store Management Tool page.
20. Verify that the list of term groups now includes a group named Navigation.
21. Expand the Navigation group, and verify that the group includes a term set named Intranet.
 Task 2: Add Navigation Terms

1. In Visual Studio, in the Program class, add a method named CreateNavigationTerms. The method
should:
o Accept an argument of type TermSet named termSet.
o Return void.
2. In the CreateNavigationTerms method, create the following terms:
Term Term
Navigation Settings
Name LCID
Home 1033 Set the _Sys_Nav_TargetUrl property to /Pages/Home.aspx.
Intranet 1033 Set the _Sys_Nav_SimpleLinkUrl property to

http://intranet.contoso.com/Pages/Home.aspx.
HR 1033 Set the _Sys_Nav_SimpleLinkUrl property to

IT 1033 Set the _Sys_Nav_SimpleLinkUrl property to

Legal 1033 Set the _Sys_Nav_SimpleLinkUrl property to

Term Term
Navigation Settings
Name LCID
Finance 1033 Set the _Sys_Nav_SimpleLinkUrl property to

3. Commit the changes to the term store.
Note: If you prefer, you can copy the CreateNavigationTerms method from the text file at
E:\Labfiles\Starter\Snippets\CreateNavigationTerms.txt.
4. In the Main method, below the existing code, retrieve the term set named Intranet from the term
group.
5. Call the CreateNavigationTerms method, passing the Intranet term set as an argument.
6. Build the solution and start debugging.

7. When the program has finished running and the console window has closed, switch to Internet
Explorer and reload the Term Store Management Tool page.
8. Expand Navigation, expand Intranet, and notice the terms in your term set.
9. Click the Intranet term set, and on the INTENDED USE tab notice that the Use this Term Set for
Site Navigation check box is selected.
10. Click the Finance term, and on the NAVIGATION tab notice that the Simple Link or Header option
is selected.
11. Click the Home term, and on the NAVIGATION tab notice the Term-Driven Page with Friendly
URL option is selected.
12. On the TERM-DRIVEN PAGES tab, notice the Target Page Settings has been configured to
/Pages/Home.aspx.
 Task 3: Pinning Terms to Navigation Term Sets

1. In Visual Studio, in the Program class, add a method named PinTermSet. The method should:
o Accept an argument of type TermSet named source.
o Accept an argument of type TermSet named target.
o Return void.
2. In the PinTermSet method, iterate over the terms in the source term set.
3. For each term in the source term set, re-use the term with pinning in the target term set.
Note: If you prefer, you can copy the PinTermSet method from the text file at
E:\Labfiles\Starter\Snippets\PinTermSet.txt.
4. In the Main method, below the existing code, call the CreateNavigationTermSet method again.
Pass the Navigation group and the string text Team as parameters.
5. Retrieve the term set named Team from the Navigation group.
6. Call the PinTermSet method. Specify the Intranet term set as the source term set and the Team
term set as the target term set.
7. Commit your changes to the term store.
9. When the program has finished running and the console window has closed, switch to SharePoint
2013 Central Administration.
10. Reload the Term Store Management Tool page.

11. Expand Navigation, and notice a new Team term set has been created.
12. Expand Team, and notice the same terms exist in the new term set as in the Intranet term set.
 Task 4: Configure and Test Managed Navigation

1. In Visual Studio, in the Program class, add a method named SetManagedNavigation. The method
should:
o Accept an argument of type SPSite named site.
o Accept an argument of type String named groupName.

o Accept an argument of type String named termSetName.
o Return void.
2. Within the SetManagedNavigation method, configure the passed-in site to use the taxonomy
provider for global navigation.
3. Retrieve the ID value of the Managed Metadata Service term store.
4. Retrieve the ID value of the term set with the passed-in term set name.
5. Use the term store ID and the term set ID to associate the site global navigation with the specified
term set.
Note: If you prefer, you can copy the SetManagedNavigation method from the text file at
E:\Labfiles\Starter\Snippets\SetManagedNavigation.txt.
6. Comment out all the existing code in the Main method.
7. In the Main method, instantiate an SPSite object in a using statement for the site at
http://intranet.contoso.com.
8. Within the using statement, call the SetManagedNavigation method. Pass the SPSite instance, the
group name Navigation, and the term set name Intranet as arguments.
9. Instantiate an SPSite object in a using statement for the site at http://team.contoso.com.
10. Within the using statement, activate the site collection publishing infrastructure feature (use the
GUID value f6924d36-2fa8-4f0b-b16d-06b7250180fa).
11. Call the SetManagedNavigation method. Pass the SPSite instance, the group name Navigation,
and the term set name Team as arguments.
Note: If you prefer, you can copy the Main method from the text file at
E:\Labfiles\Starter\Snippets\Main.txt.

Explorer and browse to http://intranet.contoso.com.
14. Notice the managed navigation items are displayed. If the navigation items are not visible, click
Refresh.
15. Click the HR node, notice that you are directed to the http://intranet.contoso.com/hr URL.
16. Click New Tab, in the address bar, type http://team.contoso.com, and then press Enter. Notice that
in the global navigation area, the pinned terms being used are similar to your intranet publishing site.
Results: A new navigation term set used by a site collection and shared by a team site.
Lesson 3
Publishing to Mobile Devices
In this lesson, you will learn about the new features in SharePoint 2013 that support mobile devices. This
includes understanding device channels and device channel panels.
Lesson Objectives
 Describe the various capabilities of mobile devices.
 Describe what a device channel is used for.
 Create and configure device channels.
 Use device channel panels.
Mobile Device Capabilities

Mobile devices and the Bring Your Own Device
(BYOD) phenomena have forced a significant
change in the way web applications are being
designed and architected. With mobile devices now
outselling personal computers and laptops, you can
see how having mobile-friendly applications should
be one of the top priorities on a developer’s list.
When it comes to browsing your web applications
and the content on them with mobile devices,
mobile devices present various challenges around
properly rendering the markup on the device. This
is a result of the devices having varying capabilities,
including:
 Screen size. Mobile devices have wildly different size screens, and each screen size will present the
content in a different way. This is important when rendering large pictures and icons, or placing ads
on the page.
 Touch support. Some devices support a touch interface. For those that do, a touch-friendly UI should
be presented, including larger buttons and easily clickable links.
 Network bandwidth. Mobile phones tend to utilize network technologies like 3G and 4G, and some of
the newer network transmission protocols such as 4G LTE. Each network technology has differing
speeds that dictate what a device is capable of downloading in short periods of time. This is
important when using large supporting files such as JavaScript libraries and images.
 Browser and browser feature support. The browser that runs on the device is also important because it
may not support some of the newer web technologies such as HTML5 or the latest versions of
JavaScript and CSS.
SharePoint 2013 has been designed to provide better support for mobile devices, and also gives you the
flexibility of changing its behavior based on your current or future devices. Out of the box, you have three
possible browsing options when using a mobile device:
 Contemporary view. The optimized browser experience for mobile browsers. This view renders in
HTML5 and has many mobile-friendly features.
 Classic view. An HTML, CHTML, WML, or similar view that is rendered on devices that do not support
HTML5.
 Full-screen UI. This is the full desktop version view of a SharePoint site.
Each view depends on the mobile device and capabilities as outlined above.
Additional Reading: For comprehensive guidance on supported mobile device browsers,

see Mobile device browsers supported in SharePoint 2013 at
Contemporary View
This new view in SharePoint 2013 provides HTML5 support and offers the following features:
 Menu button. Located on the right side of the page view, it allows a user to access “Site Contents”, or
“Sign Out”, or “Close” a particular view.
 Switch to PC View. This will switch the view from the mobile view to the full desktop view.
 Navigation window. The navigation window allows a user to browse the content in a site.
 Tap to open links. This feature allows users to more easily tap links, because they are rendered with a
wide strip that can be clicked.
 Pagination. When a list has more than 20 items, it is automatically paginated.

 New and edit functionality – Adding and editing items is highly improved.
Mobile Browser Redirection

When a mobile device requests a SharePoint page, the device will be routed to the proper mobile
experience if the Mobile Browser View feature has been activated. Not all site definitions have this feature
activated at site creation time, and you may need to activate it.
Once activated, SharePoint will interrogate the HTTP header variables and make a decision based on the
values defined in the browser definition file. This file, called compat.browser, lives in the virtual directory
of the SharePoint web application under the App_Browsers directory. When new devices are added to
your network, you may need to update this file to tell SharePoint which features the device supports and
if it is a mobile device.
Device Channels
Despite all the improvements offered out of the box
with SharePoint 2013, you may still have devices
that need even more targeted customizations to
ensure user satisfaction and adoption. If you find
you have this requirement, SharePoint 2013
provides a new feature called Device Channels.
Device channels allow you to specifically target
devices with custom master pages and CSS by using
the HTTP User Agent header that is passed with
every browser request.
Creating a Device channel is a very simply operation

and requires the following information:
 Name. A friendly name to identify the channel when configuring the master page.
 Alias. The name used to identify the channel when you reference it in code and device channel
panels.
 Description. A simple field for describing the channel and its usage.
 Device Inclusion Rules. The user-agent field that the device channel is targeted at.
 Active. Whether the device channel is ready for production use. This can be tested by using the
DeviceChannel query string, which is explored later in the module.
Note: You can have up to 10 device channels per site, and each device channel can have
up to 150 device inclusion rules.
Once you have created a device channel, you must create a master page to use with the device channel.
Ultimately, this master page would target the capabilities of the device. For example, if it has a small
screen, then you might want to replace the large images that are used on your pages with smaller ones or
remove the images completely. The logic for selecting a device channel resides in the
PublishingLayoutPage, which most pages in SharePoint inherit from. Inside the OnPreInit is where the
HTTP request is analyzed, and then the appropriate master page is selected. The mapping of a device
channel to a master page must be done by using the SharePoint UI because there are no APIs that
currently support changing it. When you make a change to a mapping, that change is saved in the master
page gallery as a file called __DeviceChannelMapping.aspx.
Ordering
In many cases, a particular device manufacturer or a particular product may include many different device
models, each with significant differences in the features they support. In this case, you will need to create
more than one channel for the same set of devices. This is where the ordering of the device channels
becomes very important. You should always have the more specific user-agent values at the top of the list
to make sure that they are called (rather than the more generic ones).
Device Channel Panels

In some cases, you may find that creating an entire
master page and CSS for a device is not a
productive task. When this is the case, you can
simply add a Device Channel panel to your master
pages. A device channel panel is a set of controls
that will be rendered only if the device channel
user-agent setting is matched. Device Channel
panels can be placed on any master page or regular
page, provided that the
Microsoft.SharePoint.Publishing.WebControls
namespace has been registered on the page. A
device channel panel is defined by the
MobilePanel class. It has one important property called IncludedChannels. The IncludedChannel
property simply contains a comma-separated list of device channel that the control is targeted to, and will
only display its child controls when that channel is activated (again based on the user-agent HTTP
header).
Note: You can test your Device Channel panels by appending the DeviceChannel
querystring to the end of your page URL:
http://teams.contoso.com/pages/default.html?DeviceChannel= WindowsPhone
You can have individually targeted content on master pages by using Device Channel Panels:
Example of a Device Channel Panel

<PublishingWebControls:DeviceChannelPanel runat=server id=mpanelwindowsphone1
IncludedChannels=Windows75Phone>
Some content targeted at Windows 7.5 Phone
</PublishingWebControls:DeviceChannelPanel>
Demonstration: Defining Device Channels

The instructor will now demonstrate how to create and configure device channels for a SharePoint Server
2013 publishing site.
Demonstration Steps

4. In Internet Explorer, in the address bar, type http://intranet.contoso.com, and then press Enter.
5. Click the Settings icon, and then click Design Manager.

6. On the Design Manager: Welcome page, in the numbered list, click 2. Manage Device Channels.
7. On the Design Manager: Manage Device Channels page, click Create a channel.
8. In the Device Channels - New Item dialog box, in the Name box, type Windows Phone.
9. In the Alias box, type WindowsPhone.
10. In the Description box, type The WindowsPhone device channel.
11. In the Device Inclusion Rules box, type Windows Phone.
12. Select the Active check box, and then click Save.
13. In the Device Channels - New Item dialog box, click Close dialog.

Lesson 4
Multi-Language Sites Using Variations
In this lesson, you will configure variations on your intranet site and then create a new French variation.
You will also learn how to export XLIFF files and how to test variations by using your browser language
settings.
Lesson Objectives
 Configure variations.
 Create new variations.

 Work with variation timer jobs and variation logs.
 Translate content using XLIFF files.
Variations
Companies that have customers and employees in
different parts of the world often require the same
content in SharePoint sites, but in different
languages. This requirement usually means you
have a source site that needs its content copied and
then translated to target sites. SharePoint provides
the Variations feature to facilitate these types of
requirements. Common scenarios include:
 Multilingual sites. As previously mentioned,

global companies may need to appeal to
customers who speak and read in different
languages.
 Multiple devices. Content that is published to target sites that have varying layouts to support specific
devices.
 Coordinating Content Creation and Updates. Ensuring that content is synchronized and managed
when you have several versions of it is a daunting task that is made easier through the use of the
variations feature.
 Accuracy of translated content. Ensuring that the content is accurately translated into the target
language.
The variation architecture is made up of the following elements:
 Variation root site. The site that will contain the landing page that will redirect users to the proper
variation sites. This site does not have to be the root site of the site collection. It cannot be changed
after you have created it.
 Variation labels. The name of the variation.
 Variation sites. There are two types of variations, source and target. Each time you create a new label,
a corresponding site will be created.
 Variations hierarchy. The entire set of sites in the variation root site, you can have only one variation
hierarchy per site collection.
 Variation lists. Lists that have been configured to be synchronized to the target variation sites
 Variation pages. Pages that are stored in the Pages library of the source variation. You should avoid
adding any other types of documents other than pages in the Pages library.
 Timer Jobs. A series of jobs will review the settings in the variation configuration and then do the
work necessary to set up any variation labels
 Event Receiver. The Pages library has several event receivers attached to it that are in charge of telling
the variations architecture that changes have been made
Note: SharePoint on-premise can have up to 209 variation labels. SharePoint Online™ can
have up to 50.
Variation redirection works by analyzing the browser’s language setting and then routing the user to the
proper variation via a redirection page. For example, if the user’s browser language is French, when the
user hits the variation root site they will be redirected to the French version (if you have created it,
otherwise it goes to the source variation). You can customize the redirection page with your own
redirection logic if you prefer to redirect based on factors other than the browser language setting.
Each time a source variation site has a new item (in most cases, a web page in the Pages library) created, a
corresponding item is created in all the target variations. This item is an exact replica of the original and
must either be translated by someone or else translated by using the machine translation service.
Note: The Variation architecture does not copy resources like images and documents. This
is a feature of the content deployment APIs.
Variation Configuration
There are several settings you can configure when you setup variations, these include:
 Site, List and Page Creation Behavior. Specifies if sites, lists, and pages of the source variation are
created automatically or manually. By default, the setting is Create Everywhere, which means they are
always created.
 Recreate Deleted Target Page. Specifies if a pages should be recreated if it is deleted in a target
variation.
 Update Target Page Web Parts. Specifies if web parts should be updated on target pages if the source
pages are updated.
 Notification. Sends email notifications to the target label contact when a new page is created, or
notifies the page owner when a page is updated.
Variation configurations are stored in several different areas including:
 Property bag of root site of site collection. These include the ID of the Relationships List and Labels list.
 Property bag of root folder of root site of site collection. This will be used to save the status of any
content deployment jobs.
 Property bag of root folder of Relationships List. This includes the Update Web Parts, Auto Spawn Stop
After Delete, Source Variation Root Web Template, Copy Resources, Enable Auto Spawn properties,
Send Notification Email, Disable Automatic Propagation, and Translate Fields properties
 List Items in Relationships List. Used to save the variation root site URL in case you move the site by
using the Site Manager feature.
 List Items in Variation Labels List. Each label created will be saved here.
 Property bag of sites in the Variation Hierarchy. Stores the link of sites to peers.
 Fields of pages in the Variation Hierarchy. Links pages and their peers.
Variation Logs
The variation system logs status information to the hidden Long Running Operation Status list in the root
of the site collection. You can use this to see the status of the various timer jobs that execute in order to
create the variations hierarchy and variation label sites.
Variation Labels
A Variation label is the name of a variation site. As
part of the configuration process, you must create a
source variation and then the target variations. The
variation label will normally correspond to the
language that the variation implements. For
example, if you create three variations called EN, FR,
and DE, you will have corresponding sites at
http://www.contoso.com/EN,
http://www.contoso.com/FR, and
http://www.contoso.com/DE.
When creating a new variation label, there are

several settings that must be configured, these
include:
 Language. These options are based on the language packs you have installed in the system. Even
though your target may be a different language in terms of content, you may find the UI in the
default language. You should ensure that both the content and the UI are translated.
 Locale. The locale that is used to determine where the browser will be redirected based on the default
browser language setting.
 Label name. The label that will be used in the site’s URL.
 Display name. The friendly name for administrators.
 Hierarchy Creation. Made up of three options that determine what language items will be translated
into. These include Sites, Lists, and Pages.
 Translation Options. Two settings that determine if human or machine translation is enabled.
 Page Update Behavior. How sync will work when a source page is updated.
 Label Contact. The person who will be contacted when the site is created, new pages are copied, and
new sites and lists are created
When creating a variation site, if you want the user interface to reflect the language of the variation, you
must make sure that the language pack has been installed. Otherwise, the site’s UI will be in your default
language, but the various pages with be in the target language (after they have been translated).
Additional Reading: For more guidance on language packs, see Install or uninstall
language packs for SharePoint 2013 at http://go.microsoft.com/fwlink/?LinkId=141342.
Timer Jobs
Once you have configured your variation hierarchy, SharePoint will create the hierarchy using Time Jobs.
These timer jobs execute in the OWSTimer.exe windows service and will only execute if that service is
running. Timer jobs include:
 Variations Create Hierarchies Job Definition. Responsible for creating the variation hierarchy on any
un-spawned labels.
 Variations Propagate List Items Job Definition. Creates and updates peer list items.
 Variations Propagate Page Job Definition. Creates and updates peer pages in the target variations.
 Variations Propagate Sites and Lists Job Definition. Creates peer sites and lists when a user creates a
variation site
Variation timer jobs implement the SPWorkItemJobDefinition job class. The reason for this is that the
worker process of the web application is not normally allowed to write to the configuration database. This
means the timer jobs must pull the workload data from the content database via work items. Once the
timer jobs have successfully completed, the work item is removed.
Translating Content
Once the source and target variations have been
configured and created, pages must be translated
to the target variation language. This can be done
one of two ways:
 Human translation
 Machine translation
Human Translation
The goal of variations is to create language-focused
versions of a particular web site. In previous
versions of SharePoint, translation workflows would
be executed to let translators know that a page
needed to be translated. This would typically occur when a page is copied from the source variation to the
target variation. This is a simple copy operation, and no translation is performed. Whatever the page’s
source language was, for example English, is what it will have in the target. The human translator will then
need to translate the page.
Machine Translation
SharePoint 2013 includes a new service application called Machine Translation. This service acts as a proxy
to the online Microsoft Translation service. Several features within SharePoint can take advantage of
machine translation. These include:
 Office Web Apps (Word and PowerPoint translation)
 Managed Metadata
 Custom applications via Machine Translation APIs
You should be careful with what you submit to machine translation. This content is submitted to Microsoft
and is available for the company to review in order to improve the translation engine. You should also
consider that machine translation is far from perfect, and a human reviewer will still need to confirm the
content was translated properly.
XLIFF Files
Pages can be exported for translation by external companies by using industry standard file formats. The
most common of the translation file formats is XML Localization Interchange File Format (XLIFF). Once
translated, these translation files can then be imported back into the variation site to update the pages.
Additional Reading: For more guidance on the XLIFF standard, see OASIS XML Localisation
Interchange File Format (XLIFF) TC at http://go.microsoft.com/fwlink/?LinkId=258217.
Variation pages can be exported to XIFF files:
Example of an XLIFF File

<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file original="8c614d79-5302-4118-888d-766375ee5792" source-language="en-US" target-
language="fr-FR" datatype="html" tool-id="SharePoint Server 2013">
<header>
<note>type=ListItem</note>
<note>translatorType=Vendor</note>
<note>packageGroupId=3a27e1ad-ac9e-4f13-8af5-4fbcb8e6f3d2</note>
<tool tool-id="SharePoint Server 2013" tool-name="Microsoft® SharePoint® Server
2013" />
<note>webId=deab7df5-cdc7-40c6-9d33-fbd6a4cf40aa</note>
<note>listId=592e0604-1706-49eb-bc0d-c1a40964d58f</note>
<note>url=Pages/default.aspx</note>
<note>sourceVersion=3</note>
</header>
<body>
<trans-unit id="fa564e0f-0c70-4ab9-b863-0177e6ddd247" datatype="plaintext">
<source>Home</source>
<note>fieldTitle=Title</note>
</trans-unit>
<trans-unit id="f55c4d88-1f2e-4ad9-aaa8-819af4ee7ee8" datatype="html">
<source>
<bpt id="0"><h2></bpt>
<ept id="0"></h2></ept>
<bpt id="2"><h2></bpt>Welcome to Your Publishing Site<ept
id="2"></h2></ept><bpt id="4"><h3 class="ms-rteElement-H3"></bpt>These links
will help you get started.<ept id="4"></h3></ept></source>
<note>fieldTitle=Page Content</note>
</trans-unit>
</body>
</file>
</xliff>
Multilingual Navigation
Each variation will have a managed term set created
for it. By default, the term set for the source
variation is called Variations Navigation. The term
set for the target is called Variations Navigation
(LabelName). Each time you create a new page, the
target variation page will be created and a new
term added to the term set. Variations will not copy
a term set term to a target site unless there is a
page associated with it. If you create any other
terms, they will not be copied. Once you have
associated terms with pages in the source site
collection, running the Variations Propagate Page
Job Definition job for the web application in which your variations site collection exists will create the re-
used terms.
When working with managed navigation and variations, consider the operation to be similar to a one-
time copy operation. This means that if you change attributes of the terms or move them into a different
place in a term hierarchy, they won’t get picked up by the variations timer jobs. If you make changes in
the terms after they’ve been pushed to the target sites, you will need to do some manual updating or
write scripts for the updates.
When you export a page for translation, the term label is also exported. When you import the package,
the term label is also updated.
Lab B: Publishing Sites for Multiple Devices

Scenario
Contoso managers would like to have a more customized experience when using their mobile phones and
other devices when browsing the intranet. They have asked you to utilize the device channel feature in
SharePoint 2013 to implement the customizations.
Objectives
 Create Device Channels.
 Configure device channel master pages mappings.
 Test device channels.
 Implement device channel panels.
Lab Setup
Estimated Time: 60 Minutes
Exercise 1: Creating a Device Channel

Scenario
In this exercise, you will create a new device channel to support Windows Phone devices. The device
channel will utilize a custom master page that you must customize to remove the site icon, which is too
large for some mobile device screens.
1. Create a New Device Channel
2. Create and Configure a New Device Channel Master Page
3. Test the Device Channel and Master Page
 Task 1: Create a New Device Channel

2. Open the device channels settings for the site.
3. Create a new device channel with the following properties:
a. Set the Name to Windows Phone.
b. Set the Alias to WindowsPhone.
c. Set the Description to The Windows Phone mobile channel.
d. Add Windows Phone to the device inclusion rules.

e. Set the device channel to Active.
 Task 2: Create and Configure a New Device Channel Master Page

1. Browse to the master page gallery.
2. Upload the file at E:\Labfiles\Starter\WindowsPhone.master to the gallery.
3. Set the content type to ASP.NET Master Page.

4. Set the compatible UI versions to 15.
5. Publish a major version of the WindowsPhone.master page.
6. Open SharePoint Designer, and then open the site at http://intranet.contoso.com.
7. Open the WindowsPhone.master page in the SharePoint Designer editor.
8. Locate and delete the div element with an id value of siteIcon.
9. Save the file, close SharePoint Designer, and switch back to Internet Explorer.
10. In the site settings for the site at http://intranet.contoso.com, specify that the Windows Phone
device channel should use the WindowsPhone master page.
 Task 3: Test the Device Channel and Master Page

1. Browse to the site home page, and then open F12 Developer Tools.
2. In F12 Developer Tools, change the user agent string to Windows Phone, and then reload the page.
3. Notice that the site icon is no longer displayed.
4. Close F12 Developer Tools and close Internet Explorer.
Results: After completing this exercise, you should have configured a device channel for Windows Phone
devices.
Exercise 2: Using Device Channel Panels

Scenario
You have been asked to create a device channel panel that targets the device channel you created in the
previous exercise.
1. Add a New Device Channel Panel
2. Test the Device Channel Panel
 Task 1: Add a New Device Channel Panel

2. Browse to the master page gallery.

3. Upload the file at E:\Labfiles\Starter\custom.master to the gallery.
4. Set the content type to ASP.NET Master Page.
5. Set the compatible UI versions to 15.
6. Publish a major version of the custom.master page.

7. Open SharePoint Designer, and then open the site at http://intranet.contoso.com.
8. Open the custom.master page in the SharePoint Designer editor.
9. Add a Register directive for the following namespace and assembly:
a. TagPrefix: PublishingWebControls
b. Namespace: Microsoft.SharePoint.Publishing.WebControls
c. Assembly: Microsoft.SharePoint.Publishing, Version=15.0.0.0, Culture=neutral,

PublicKeyToken=71e9bce111e9429c
Note: You can copy the Register directive from the text file at
E:\Labfiles\Starter\Snippets\PublishingWebControlsTagPrefix.txt.
10. Locate the ContentPlaceHolder control with an id value of PlaceHolderMain.
11. Immediately above the located code, add a DeviceChannelPanel element with the following
properties:
a. Set the ID attribute to mpanelwindowsphone1.
b. Set the IncludedChannels attribute to WindowsPhone.

c. Set the content of the element to Welcome Windows Phone User!
Note: If you prefer, you can copy the DeviceChannelPanel element from the text file at
E:\Labfiles\Starter\Snippets\DeviceChannelPanel.txt.
12. Save the file, close SharePoint Designer, and switch back to Internet Explorer.
13. In the site settings for the site at http://intranet.contoso.com, specify that all device channels
should use the custom master page.
 Task 2: Test the Device Channel Panel

1. Browse to the site home page, and verify that the page renders normally.
2. Open F12 Developer Tools, and change the user agent string to Windows Phone.
3. Reload the page, and notice that the page now includes a welcome message for Windows Phone
users.
Results: After completing this exercise, you should have configured a master page to use device channel
panels to display content to users of specific devices.

In this module, you learned how to work with publishing sites in SharePoint Server 2013. You learned
about how to configure website structure and navigation, and you gained an understanding of various
publishing scenarios. You also learned how to configure sites to support multiple devices and languages.
Review Question(s)
Question: What will be your SharePoint navigation strategy?
Statement Answer
True or False: A Search service application is

required for cross-site publishing.
Statement Answer
True or False: Variations automatically

translate synchronized content.
Test Your Knowledge

Question
What is the maximum number of device channels you can have?
10
Statement Answer
True or False: Any term set can be used as a

navigation term set?
Statement Answer
True or False: Target variations will display in

the locale by default.
8-1
Module 8
Developing Optimized Internet Sites
Contents:
Module Overview 8-1
Lesson 1: Optimizing a SharePoint Site for Search Engines 8-2
Lesson 2: Optimizing Performance and Scalability 8-12
Lab: Optimizing SharePoint Publishing Sites 8-23
Module Overview
While most of the attention when building an Internet-facing site is focused on layout and content, your
site will not be successful if nobody can find it, or if poor performance degrades the user experience.
Internet users today have very short attention spans. You need to grab their attention when they search
for content and provide a fast and accurate user experience when accessing site content. To mitigate
these concerns, it is important to optimize Internet sites for search engines, and to ensure that the site
provides the best possible performance for the user’s device, browser, and network characteristics.
In this module, you will learn how to optimize your site for Internet search engines and how to maximize
the performance of rendering your site content.
Objectives
 Configure search engine optimization settings.
 Add SEO Properties to publishing pages and Managed Navigation terms.
 Configure caching to improve site rendering performance.
 Optimize site assets and resources to maximize performance.

8-2 Developing Optimized Internet Sites
Lesson 1
Optimizing a SharePoint Site for Search Engines
Microsoft® SharePoint® 2013 includes a number of new features to assist with search engine
optimization (SEO), and helps to ensure that SharePoint is a great platform for Internet-facing web sites.
These new features include the ability to define user-friendly and canonical URLs for pages, support for
Sitemaps and the Robot Exclusion Protocol (also known as robots.txt), and the ability to define SEO
properties on pages, including browser title, description, and keywords. This lesson will discuss the new
SEO capabilities in SharePoint 2013, and demonstrate how to configure SEO settings and properties.
Lesson Objectives
 Describe the elements of search engine optimization.
 Configure XML sitemap auto-generation.

 Exclude content from Internet search crawling.
 Configure custom meta tags and canonical URLs to improve analytics and boost ranking.
 Set SEO properties for publishing pages and Managed Navigation terms.
Elements of Search Engine Optimization

When many people think of SEO, they often focus
on organic search ranking, which is the order in
which search results are shown to a user. Ranking
algorithms used by Internet search engines are
closely guarded secrets and are constantly
changing. Up until a few years ago, search engines
relied heavily on content and meta tags contained
in a page to compute search rankings. This made
search-related meta properties like page title,
description, and keywords a high-priority
consideration for marketing-related business
objectives.
Today, most Internet search engines rely much more heavily on “off page” factors like external link
analysis and click-through statistics to determine rankings. In other words, it is the value of the content on
your site, its popularity with other sites, and prior search click-through activity, that primarily determine
search ranking.
Despite changes in the Internet search ranking process, optimizing your pages for Internet search is still
highly relevant. There are a number of goals that need to be considered for Internet search optimization:
 Crawl Frequency and Relevancy. Site contents will not be displayed in organic Internet search results
until the site is crawled and indexed by Internet search engines. The Sitemap and Robot Exclusion
Protocols can help provide guidance to Internet search engines to help ensure a site’s relevant
content can be crawled effectively, and exclude content that is not relevant for Internet search
purposes.
 Search Results Formatting. SEO-related meta properties on pages may not be highly relevant for
search ranking, but they are used by many search engines when rendering search results. SEO
properties on pages provide content authors control over how content links in search results are
displayed.
 Crawl Accuracy and Analytics. Two factors that can impact search ranking are related to how
accurately search engines can interpret a site’s navigation and structure and to accurately crawl and
index a site’s content. The more accurately search engines can crawl a site’s structure, the better they
can eliminate indexing errors associated with content duplication, and the more accurately they can
measure click-through analytics to boost popular content.
SharePoint 2013 now supports SEO settings and properties to help meet each of these goals.
Generating Sitemaps
Internet search engines find content on the internet
by crawling domain names, and then by following
hyperlinks to additional content. While it is likely
that search engines will eventually find and crawl
your site’s content, generating and submitting a site
map can help ensure that your content is crawled
more quickly and completely.
Note: Internet search crawlers can only access

publicly accessible content. To enable your
SharePoint site to be crawled from external Internet
search engines, anonymous access must be enabled
on your site.
Sitemaps are used to provide links and metadata to search engines about pages available on your site for
crawling. In addition to the hyperlink to the content item, additional metadata can be provided, including
the last time the item was updated, topic category, license, and so forth.
Reference Links: SharePoint generates an XML Sitemap by using the Sitemap Protocol that
is supported by most search engines, including Microsoft Bing, Yahoo, and Google. You can find
more information about the Sitemap standard at http://go.microsoft.com/fwlink/?LinkId=320800
SharePoint 2013 now provides native support for auto-generating an XML Sitemap by using the timer job
named Search Engine Sitemap job. A separate instance of this timer job is configured for each web
application in the farm, and by default, is scheduled to run daily. To include a site collection in sitemap
generation requires activating the Search Engine Sitemap feature at the Site Collection level.
The following sample demonstrates how to activate the Search Engine Sitemap feature on a site
collection, and then manually run the related timer job using PowerShell:
Activate and Run Search Engine Sitemap

Enable-SPFeature -Identity ‘XmlSitemap’ -Url ‘http://www.contoso.com’
Get-SPTimerJob ‘Search Engine Sitemap job’ | Start-SPTimerJob
Once the timer job has been run, a file named sitemap.xml is written to the root folder of the site
collection top-level site. This file can provide links to multiple XML Sitemap instances. SharePoint 2013
generates separate Sitemap files for standard and mobile views of the site.
The following is an example of the generated sitemap.xml file:
Sample sitemap.xml
<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<sitemap>
<loc>http://www.contoso.com/sitemap0.xml</loc>
</sitemap>
<sitemap>
<loc>http://www.contoso.com/sitemap_mobile0.xml</loc>
</sitemap>
</sitemapindex>
The actual content of each generated Sitemap.xml file is based on SharePoint search indexing. If your
Sitemap is empty, run a full crawl on the site and then re-run the Search Engine Sitemap job.
Excluding Content from Internet Search

The Sitemap protocol can work in conjunction with
another protocol called Robot Exclusion. Once the
Search Engine Sitemap feature has been enabled on
a site collection, SharePoint 2013 will auto-generate
a “robots.txt” file in the root folder of the site
collection. While a Sitemap is designed to advise a
web crawler what site content to index, Robot
Exclusion advises a web crawler what to ignore.
Robot Exclusion Protocol

The Robot Exclusion Protocol is a de facto standard
supported by many Internet search engines to allow
sites to provide instructions to web crawlers to
ignore individual pages or entire paths of a website. The protocol was developed by consensus in 1994,
and although not officially maintained by any standards organization, it is supported by most of the
popular Internet search engines including Yahoo, Google, Bing, Ask, and Baidu.
The Robot Exclusion Protocol is enabled by placing a file named “robots.txt” in the root folder of a web
site domain and is specific to a domain.
The robots.txt file is typically comprised of two directives:
 User-agent. Used to target web crawlers from specific search engines. The default wildcard * indicates
that the following section applies to all robots.
 Disallow. Used to provide the partial or full path to the content to exclude. To exclude a directory,
include the trailing / character. For a specific page, include the full URL to the page, including the
page file name and extension, if applicable.
Additional directives can also be included:
 Sitemap. Used to provide the full URL to an XML file supporting the Sitemap protocol.
 Crawl-delay. Used to specify the number of seconds to wait between crawl requests. Also used to
throttle the load that external crawlers can place on the site.
The following is an example of the default robots.txt file that is generated by SharePoint 2013 when the
Search Engine Optimization feature is enabled on a site:
Default robots.txt File

User-agent: *
Disallow: /layouts/
Disallow: /_vti_bin/
Disallow: /_catalogs/
Sitemap: http://www.contoso.com/sitemap.xml
It should be noted that the robots.txt file is purely advisory and may be ignored by malware crawlers that
may be trying to harvest phone numbers or email addresses from your site, or may be looking for security
vulnerabilities.
Additional Reading: You can find additional details and formatting examples at
SharePoint provides the ability to view and customize the directives that are written to the robots.txt file
from the Search Engine Sitemap Settings found under Site Collection Administration. The value of the
Internet Search Engine Exclusion setting is stored in the property bag of the root web of the Site
Collection with a key of “xmlsitemaprobotstxtpropertyname”. Property bag settings can be viewed by
using Microsoft SharePoint Designer 2013, or can be accessed programmatically.
The following code sample demonstrates how to read and update the Internet Search Engine Exclusion
setting using PowerShell:
Read and Update the Internet Search Engine Exclusion Setting

# open the root web of the target site collection
$web = Get-SPWeb 'http://www.contoso.com'
# read the robots.txt content and append a new directive

$robots = $web.Properties['xmlsitemaprobotstxtpropertyname']
$robots = $robots + "`rDisallow: /Legal/"
# update the property

$web.Properties['xmlsitemaprobotstxtpropertyname'] = $robots
$web.Properties.Update()
$web.Update()
Configuring Site Collection SEO Settings

Search Engine Optimization settings are available at
the Site Collection Administration level to support
SEO characteristics that should be applied to an
entire publishing site. Two settings are available:
 Verify ownership of this site with search engines.

This setting is used to add custom metadata
tags to the header area of every page rendered
on the site. These tags are typically used for
integration with third-party services including
search engine statistics and web analytics, or,
for ecommerce-enabled sites, integration with
shopping cards and payment processing.
 Consolidate link popularity with canonical URLs. This setting is used to indicate whether search
crawlers should filter parameters used in page URLs or crawl each combination of parameters as a
unique content item.
The ability to consolidate links is a very important concept for SEO. Web pages often use URL parameters
to provide directives to client or server-side code related to rendering page content. Some URL
parameters influence the content displayed, and some don’t. URL parameters may be used to impact
visual layout (for example, /news.aspx?format=print), or they may be used to filter data results (for
example, /news.aspx?year=2013&month=12).
The problem with these kinds of URL parameters is that search engines have a difficult time
understanding which URL is the best URL to show in search results, particularly if the pages have
significant duplication of content. To address this issue, some search engines now support a Canonical
URL tag that can indicate which URL parameters produce meaningful changes in page content, and which
should be ignored. The tag is inserted as a link reference that indicates the URL of the page to crawl. If the
URL is not the same as the URL of the current item, the crawler will process the link reference as a redirect
and crawl the URL provided as canonical instead. One way to look at these links is that they are similar to
an HTTP 302 redirect, but specific to search crawlers.
The following is an example of the canonical tag that is inserted into the <HEAD> section of a rendered
Publishing Page. The link will include only filtered parameters:
Sample Canonical URL Tag

<link rel=”canonical” href=”http://www.contoso.com/products?category=steroids” />
SharePoint 2013 takes care of inserting the correct tag into the site Master Page through the use of a
delegate control. The delegate control must be present in the Master Page in order for this feature to
work correctly. The SharePoint 2013 Site Collection SEO settings provide the ability to specify “Filter link
parameters”, which are the URL parameters that produce a meaningful change to the content rendered.
By entering one or more filter parameters, all other parameters will be ignored and only the specified
parameters will be crawled. SharePoint will then use the specified values to generate and insert the correct
canonical tag into the rendered publishing page.
Note: SEO settings are available only on site collections that have the Publishing
Infrastructure site collection feature enabled. This feature is automatically activated on sites
created from the Publishing Site template.
Working with Publishing Page SEO Properties

To improve support for SEO, SharePoint 2013 now
supports a collection of properties that are
associated with each publishing page in a site. The
supporting site columns and UI elements are
installed by activating the Search Engine
Optimization site feature. This is a hidden feature,
so you won’t find it listed in the SharePoint UI. The
feature is activated on publishing sites by default.
SEO properties are available from the Page tab of

the ribbon menu when editing a publishing page in
the browser, or they can be accessed
programmatically. The following is the list of
displayed settings:
Property Description
Title The value displayed in the page title area and navigation. This is the
standard Title field found on all content items in SharePoint.
Browser Title The value displayed title bar of the browser.
Meta Description A brief description of the page. This value is commonly used as the link
description by Internet search engines.
Keywords A comma-separated list of keywords to be associated with the page

content. This value is rarely used by Internet search engines.
Sitemap Priority Provides guidance for search crawlers on the relative priority of this page
content. This value is used when generating the XML Sitemap.
Sitemap Change Provides guidance for search crawlers on the anticipated change frequency
Frequency of this page. This value is used when generating the XML Sitemap.
Exclude from Used to advise web crawlers to ignore this page. This value is used to render
Internet Search a <META> tag in the rendered publishing page.
Engines
The location where SEO property values are stored depends on the Navigation Settings of the site. If the
site is using the default Structured Navigation, SEO property values are stored as hidden fields on the
publishing page item. If the site is using the new Managed Navigation introduced in SharePoint 2013, the
values of SEO properties are stored as a set of hidden custom local properties on the Navigation Term
associated with the publishing page.
Programming SEO Properties with Structured Navigation

Structured Navigation is the navigation model that
was used in earlier versions of SharePoint Server,
and is still the default in SharePoint 2013 when
creating a new site based on the Publishing Portal
site template. When using Structured Navigation,
SEO properties are stored on a collection of hidden
site columns that are automatically added to the
Page content type, which is the base content type
for all publishing pages.
The following table identifies the column static

name associated with each property displayed in
the SEO Properties edit form.
Property Static Name Type
Browser Title SeoBrowserTitle Text
Meta Description SeoMetaDescription Text
Keywords SeoKeywords Text
Exclude from Internet Search SeoRobotsNoIndex Boolean

Engines
In addition to being hidden, each of these columns is sealed and marked to deny deletion. In other words,
these fields should not be modified.
Note: The fields supporting SEO are provisioned by the Search Engine Optimization
feature. You can review the field details by examining the feature located under the SharePoint
root folder at 15\TEMPLATE\FEATURES\SearchEngineOptimization.
Although these fields are hidden, they are available programmatically as columns on any publishing page
item in the Pages library of a publishing site. These settings can be read or modified by using PowerShell,
the server-side object model, or the client-side object model and REST API.
The following code example demonstrates how to open a publishing page item and read the SEO
properties by using PowerShell:
Read SEO Properties on a Publishing Page

# open a publishing site
$web = Get-SPWeb -Identity 'http://www.contoso.com'
# open the site welcome page

$homePage = $web.GetListItem($web.RootFolder.WelcomePage)
# read the seo columns

$seoColumns = @('SeoBrowserTitle', 'SeoMetaDescription', 'SeoKeywords',
'SeoRobotsNoIndex')
$seoColumns | ForEach-Object {
Write-Host $_ " = " $homePage[$_]
}
Programming SEO Properties with Managed Navigation

Managed Navigation is a new feature of SharePoint
2013. It provides the ability to use a site collection
Term Group within a Managed Metadata Service
term store to configure user-friendly URLs that are
associated with publishing pages. When using
Managed Navigation instead of Structured
Navigation, the SEO properties associated with a
publishing page are stored as Custom Local
properties on the Navigation Term associated with
the page.
The following table identifies the custom local

property keys associated for each property
displayed in the SEO Properties edit form.
Property Custom Local Property Name Type
Browser Title _Sys_Seo_PropBrowserTitle String
Meta Description _Sys_Seo_PropDescription String
Keywords _Sys_Seo_PropKeywords String
Exclude from Internet Search _Sys_Seo_PropSiteNoIndex Boolean (as String)

Engines
Similar to the hidden columns used for SEO Properties when using Structured Navigation, the properties
are prefixed with “_Sys”, making them hidden. If you access the Navigation Term through the SharePoint
UI, the SEO properties will not be visible to users.
The following code example demonstrates how to access the SEO properties on a Navigation Term by
using PowerShell:
Read SEO Properties on a Navigation Term

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint")
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Taxonomy")
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Publishing")
$NavTermSetType = [Microsoft.SharePoint.Publishing.Navigation.NavigationTermSet]
# Open a Taxonomy Session to the Managed Metadata Service

$siteUrl = 'http://www.contoso.com'
$taxSession = Get-SPTaxonomySession -Site $siteUrl
# Open the Site Collection term group

$site = Get-SPSite -Identity $siteUrl
$termStore = $taxSession.DefaultSiteCollectionTermStore
$termGroup = $termStore.GetSiteCollectionGroup($site)
# Find the Navigation

$termGroup.TermSets | ForEach-Object {
$navTermSet = $NavTermSetType::GetAsResolvedByWeb($_, $site.RootWeb,

'GlobalNavigationTaxonomyProvider')
$termSet = $navTermSet.GetTaxonomyTermSet()
if ( $navTermSet.IsNavigationTermSet -eq $true ) {
$navTermSet.Terms | ForEach-Object {
$term = $termSet.GetTerm($_.Id)
Write-Host $term.Name
# read the seo columns

$seoProps = @('_Sys_Seo_PropBrowserTitle', '_Sys_Seo_PropDescription',
'_Sys_Seo_PropKeywords', '_Sys_Seo_PropSiteNoIndex')
$seoProps | ForEach-Object {
Write-Host $_ " = " $term.LocalCustomProperties[$_]
}
}
}
}
Demonstration: Reading SEO Properties

In this demonstration, your instructor will show how to view and edit SEO properties on publishing pages,
and how to programmatically access SEO properties from Page and NavigationTerm objects.
Demonstration Steps

3. From Internet Explorer®, browse to http://www.contoso.com.
4. If not already signed-in, click the Sign In link.
5. Click the site actions menu, then click Edit page.

6. From the Page tab on the ribbon menu, click Edit Properties, and then click Edit SEO Properties.
7. Enter a selection of sample values for each property, and then click OK.
8. Click the Publish tab from the ribbon menu, and then click Publish.
9. From the Publish dialog box, click Continue.
10. Open File Explorer and browse to the E:\Democode\PowerShell folder.
11. Right-click Get-PageSEOProperties.ps1 and select Edit.
12. Note that the code is reading column values on page list item that stores SEO properties.
13. Press the F5 key to run the script.
14. Note that the column values match the sample values you entered in a previous step.
15. From Internet Explorer, browse to http://www.contoso.com/news.
16. If not already signed in, click the Sign In link.
17. Click the site actions menu, and then click Edit page.
19. Note that the UI to edit the SEO properties is the same regardless of whether the site is using
Structured or Managed Navigation.
20. Enter a selection of sample values for each property, and click OK.
21. Click the Publish tab from the ribbon menu, and then click Publish.
22. From the Publish dialog box, click Continue.

23. Open File Explorer and browse to the E:\Democode\PowerShell folder.
24. Right-click the Get-TermSEOProperties.ps1 and select Edit.
25. Note that the code is now accessing a NavigationTermSet associated with the site collection, and
reading SEO properties from the NavigationTerm local custom properties collection.
26. Press the F5 key to run the script.

27. Note that the property values match the sample values you entered in a previous step.
Lesson 2
Optimizing Performance and Scalability
Publishing sites, whether Internet-facing or internal, are generally designed to serve content to a wide and
potentially very large audience. This makes investing in optimizing performance a high priority, both in
terms of providing the best user experience possible across today’s wide array of devices and browsers,
but also to help minimize infrastructure costs for hosting the site and to provide optimal scalability to
meet peak performance demands.
This lesson will explore a variety of techniques that can applied to SharePoint publishing sites and web
content to optimize for client- and server side-performance, and for optimal scalability.
Lesson Objectives
 Describe techniques for optimizing the performance and scalability of publishing sites.
 Describe how client-side programming can improve the performance of web sites.
 Configure SharePoint cache settings.
 Optimize images for linking and embedding.

 Optimize how site resources are linked and downloaded by a browser.
Client-Side Programming
Client-side programming is increasingly being used
to enhance the user experience and the
performance of web sites and applications.
JavaScript embedded in web pages provides the
ability to intercept user mouse and keyboard
actions, and process the events locally within the
browser, on the user’s device. If additional data
from the server is required, efficient background
data calls can be performed without requiring the
entire page to be posted back to the server.
SharePoint 2013 supports three web service

interfaces to support client-side programming:
SOAP-based web services, the Client Side Object Model (CSOM/JSOM), and the REST API. The SOAP-
based web services have been deprecated in SharePoint 2013 but are still supported. For customizing
SharePoint pages with JavaScript, either the REST API or the JavaScript Object Model (JSOM) is preferred.
The following example demonstrates how to make an Ajax call by using jQuery and the SharePoint 2013
REST API to retrieve list items:
Ajax and the REST API

$.ajax({
url: url + "/_api/web/lists/getbytitle('" + listName + "')/items",
method: "GET",
headers: { "Accept": "application/json; odata=verbose" },
success: function (data) { },
error: function (data) { }
});
Additional Reading: For more information on programming with the SharePoint 2013
REST API, read Get Started with the SharePoint 2013 REST Service on MSDN at
Additional Reading: For more information on programming with the SharePoint 2013
JavaScript Object Model, read “How to: Complete basic operations using JavaScript library code
in SharePoint 2013” on MSDN at http://go.microsoft.com/fwlink/?LinkId=320804
Minification and Bundling

The process of rendering a web page in a browser
starts with an HTTP request to download an HTML
source file from a web server. As part of parsing and
processing the HTML file, the browser will make
subsequent download requests for link references
to JavaScript, CSS, and image files. The entire
process to completely render the web page content
may involve downloading dozens of additional
static resource files. Optimizing this process can
have a dramatic effect on the performance of
rendering a web page.
Minification
Source code files contain a lot of extra content related to formatting. Characters like tabs, line breaks,
block delimiters, and comments make it readable for other programmers, but it also increases the file size,
often considerably. Many computer languages go through a process of compilation to create an
executable file; source code formatting and commenting are ignored by this process, so the extra
characters are of little concern.
The sources for web-based programming languages such as HTML, CSS, and JavaScript, however, are
parsed and processed natively by the web browser as part of rendering page content. Since the HTTP
protocol is a text-based protocol, all of these extra characters (including whitespace) contribute to the
page weight, the number of bytes that have to be downloaded from a web server to the client device to
render a web page.
Minification refers to striping all characters that are not functionally required from source code in order to
minimize the file size. This reduces the time required to download the files to the browser, and
subsequently the amount of time needed for the browser to render the web page to the user. Minification
is most commonly used for JavaScript source files, but it is equally effective for CSS and even static HTML
files.
Minification is typically performed by developers as part of packaging and deploying a website. There are
a variety of web-based and desktop utilities available to developers to support minification, as well as
extensions for popular development studios.
Bundling
It is common for web designers and developers to componentize source files by breaking out CSS and
JavaScript files into many separate files in order to facilitate team-based development, source code
control, and versioning. It is also common to utilize controls and plugins from third-party vendors or
open-source projects (for example, jQuery) that come with their own CSS and/or JavaScript resources.
The result of this practice is that as the number of CSS and JavaScript files increases, so does the load time
of a page. Each static resource linked or referenced from an HTML page generates an additional HTTP
request to a server to download the file. Browsers limit the number of downloads that can be executed at
one time; the default for most browsers is between two and eight. If the HTML page requires additional
resources, the download requests are queued, and the time to render the page is increased.
Bundling, similar to the process of minification, combines multiple source files into a single file. The result
is that a smaller number of files are linked or referenced from the HTML page, and the browser is required
to perform fewer additional download requests to the server, reducing the bandwidth overhead
associated with each request and reducing the total time to download required resources and to render
the page.
Reference Links: Visual Studio® Web Essentials in an extension for Microsoft Visual Studio
2013 that can perform minification and bundling for CSS and JavaScript files. You can down the
extension from http://go.microsoft.com/fwlink/?LinkId=320806
Caching
SharePoint 2013 provides a number of caching
technologies to help optimize the performance of
publishing sites.
Note: In many cases, developers will not have

the access permissions required to configure
caching. Instead, developers must understand
caching and be able to communicate their caching
requirements to farm administrators.
BLOB Cache
The BLOB cache is used for caching large static resources such as images, audio, and video, as well as files
like CSS and JavaScript. Normally, these resources are stored by SharePoint in the content database in SQL
Server®. When a page is rendered for the first time, all of these resources must be retrieved from the
database before being delivered to the client. The BLOB cache is configured and runs on the front-end
web server. By caching these files, which will not change frequently, network traffic with SQL Server is
reduced, and page load times decrease. In addition to the performance benefits, the BLOB cache
integrates with IIS media streaming, which enables large video and audio files to begin playback in the
browser without requiring the entire file to be completely downloaded to the client.
Configuring the BLOB cache requires making changes to the web.config file and is disabled by default
when creating a new SharePoint web application. Since the setting is enabled or disabled for all site
collections within a web application, it should be considered when planning the Information Architecture
for your SharePoint sites.
Considerations for configuring the BLOB cache include:
 Location. The cache is stored on disk on the front-end web server. It is recommended that the cache
be placed on a high-performance disk.
 Included Files. The files that will be cached are defined by file extension. For publishing sites that
display content that may be changed infrequently, it is recommended to cache as many different file
types as possible.
 Size. The size in MB determine how large a cache to support. The default is 10GB and should be sized
roughly 20% larger than the amount of content expected to be cached.
The BLOB cache is also required to support image renditions on publishing sites.
The Output Cache

Pages on publishing sites can be quite complex, composed of many dynamic content areas that require
querying various service applications and databases in order for the web server to render and deliver the
page to the client browser.
The output cache is an in-memory cache used to store the rendered output of a page. Since the content
displayed on a page may vary based on the permissions of each user, separate versions of pages are
cached for each unique permission set. The utility of the output cache is strongly tied to publishing sites
that support anonymous users, or authenticated users who typically share the same permission set.
The output cache can be configured at the site collection level, or for an entire web application by making
a modification to the web.config file. If the Output cache is configured in the web.config file, it will
override the cache configuration settings at the site collection level for all site collections contained in that
web application.
Object Cache
The object cache is an in-memory cache commonly used by developers to implement caching at a
component level, such as a web part. The object cache is used to store query results for settings, list and
library data views, and page layouts. By reducing the calls to the SQL Server database, the object cache
helps reduce traffic between the web front-end servers and the SQL database servers, and improves the
overall speed at which pages are rendered and delivered to the client.
The object cache requires minimal configuration. The size of the cache can be configured at the site level
or at the web application level.
Anonymous Search Results Cache

SharePoint 2013 makes a huge investment in bringing the power of search to publishing portals. The new
Content By Search Web Part is the recommended way for surfacing almost all forms of dynamic content,
even typical article pages on publishing pages. To improve the performance of publishing sites that make
heavy use of search for surfacing content, the Anonymous Search Results Cache was introduced to cache
search results for anonymous users that match the same query.
Additional Reading: For more information, read the Plan for caching and performance in
SharePoint Server 2013 on Microsoft TechNet at http://go.microsoft.com/fwlink/?LinkId=320808
Optimizing Image Resources

The demand for visually appealing websites ensures
that many websites make heavy use of graphical
images including logos, icons, cliparts, and high-
resolution stock photography.
Web Optimize Images

Much of the problem with images in websites is
that the images are not optimized for presentation
on a website. The following are two examples of
techniques that can be used to optimize image
resources:
 Choose the right format. Different graphic

formats such as PNG, JPG, and GIF are suited to specific types of graphics. The GIF format is well
suited to line art, and PNG and JPG are generally better choices for high-resolution photos.
 Avoid Scaling. HTML and CSS support scaling an image to display at a resolution greater or smaller
than its native resolution. Scaling an image does not reduce the size of the image that is downloaded
from the server to the browser, even if the image appears to be much smaller than it actually is. It is
common to add high-resolution images to a website that are much larger than necessary. It is always
advisable to resize images to an appropriate size and resolution before they are added to a website.
Note: Image Renditions is a new feature in SharePoint 2013 that resizes images
automatically to a set of pre-determined sizes. We cover this new feature in more depth later in
the lesson.
Web Fonts
The number of fonts supported by HTML across browsers (referred to as web-safe fonts) has always been
quite limited. Web designers wanting to utilize fonts not supported natively by browsers commonly
resorted to rendering styling text as images.
The @font-face feature introduced with CSS3 and HTML5 now supports the ability to download custom
typefaces. Some of the advantages of web fonts include:
 Searchable
 Accessible for assistive technologies like screen readers

 Translatable
 Dynamically scalable
Similar to images, web fonts have to be downloaded by the browser. Like many features in the HTML5
umbrella of capabilities, there continue to be issues regarding support across devices and browsers, so be
sure to use progressive enhancement techniques when considering web fonts.
CSS with Base64 Embedded Image

HTML and CSS support the ability to use a data URI to embed image data instead of linking to external
image elements. A data URI can be used to replace a link to an external image, and instead embeds the
image into the CSS file by using Base64 text encoding. The following is the format of a data URI:
data:[<mime type>][;charset=<charset>][;base64],<encoded data>
The advantage of this technique is that it reduces the number of files that need to be downloaded by the
browser. However, the technique inflates the size of the CSS file considerably. Base64 encoding also adds
about 10% to the size of the original image due to the encoding. It also precludes using separate caching
strategies for images.
The following is an example of using a data URI in a CSS element:
Setting a Background Image with a Data URI

img.icon {
background:
url(data:image/gif;base64,AAORHHfOulrSZu6qvchuaSIDFHsafd;lsaf;lkjsdaf89jsdfl <…>);
}
Using a data URI can make sense if the images are very small and are only referenced once through a CSS
file.
Image Sprites
An Image sprite is a collection of images that are consolidated into a single image file. Using sprites allows
the browser to download and cache a single file instead of having to make multiple server requests,
minimizing bandwidth and improving page load performance.
Sprites are used in combination with CSS capabilities that allow image references to render only a portion
of an image. The position and dimension of the image to render is controlled by using the height and
width of the <IMG> element combined with the left and top properties of the background element.
The following is an example of how CSS is used with a sprite. In this example, a single sprite image file
contains a collection of 64px x 64px icons. As the user moves the mouse over the search icon, the left
starting position of the background position is shifted 64 pixels:
Using Sprites in CSS

img.search {
background: url(navicons_sprite.gif);
background-position: 0 0;
width: 64px;
height: 64px;
}
img.search:hover {
background-position: 64px 0;
}
Sprites are a particularly good choice for collections of images that share a common purpose and size,
such as navigation icons that include variations such as hover transitions, or are themed for different color
selections. When images in a sprite share common dimensions, it makes it easier to calculate the offsets
required when referencing them in CSS.
Using Image Renditions

A common problem experienced on many Internet-
facing sites is the need to display the same image at
different resolutions. A typical example is an article
that requires a small thumbnail or rollup image
when displayed in a news feed. Another emerging
challenge facing web designers and developers is
the proliferation of smartphones, tablets, gaming
consoles, and other devices beyond the traditional
PC, which now provide the ability to browse the
Internet. These devices have introduced a wide
variety of screen resolutions and orientations. The
web community has responded with techniques
such as responsive and adaptive web design that tailor the user experience of the site for mobile devices
by changing the flow and size of text and images on the page.
Since image quality typically degrades when an image is scaled to a higher resolution, most images are
uploaded at a high resolution and then scaled down by the browser when displayed at a lower resolution
(such as a thumbnail). This requires the full-size image to be downloaded to the browser, even though it
may be displayed in a significantly smaller resolution. This can drastically increase bandwidth
requirements and page load times.
Image renditions allow an original source image in SharePoint to be resized to a pre-defined set of
alternative height and width dimensions called a “Rendition”. For example, a site may have three defined
renditions for images used in articles; thumbnail (100px x 100px), newsfeed (220px x 100px), and article
detail (400px x 300px). For image resolutions where the aspect ratio (ratio of height to width) is not
consistent with the original image, authors can crop the portion of the image shown for each rendition
when the page is displayed.
Configuring Image Renditions

Image renditions are configured through the SharePoint UI, and can be accessed from the Site Settings
page. The Image Renditions link is located under the Look and Feel group heading. You can also access
the configuration page from the Design Manager. SharePoint 2013 publishing sites come pre-configured
with a set of renditions for use with out-of-box display templates, but you can also customize or create
your own.
Somewhat atypically for SharePoint, the configured list of renditions is serialized and stored in a file
located in the Master Page Gallery at
~SiteCollection/_catalogs/masterpage/PublishingImageRenditions.xml.
Working with renditions programmatically is done through the SiteImageRenditions class, which is
contained in the Microsoft.SharePoint.Publishing namespace and assembly.
The following example demonstrates how to retrieve the collection of renditions through PowerShell:
Getting a List of Image Renditions

Add-PSSnapin "Microsoft.SharePoint.PowerShell" -ErrorAction Ignore
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Publishing")
# open a publishing site and get the list of image renditions

$site = Get-SPSite 'http://www.contoso.com'
$renditionsList =
[Microsoft.SharePoint.Publishing.SiteImageRenditions]::GetRenditions($site)
Write-Output $renditionsList
Image renditions are only available on publishing sites, and require configuration of the BLOB cache. If
the BLOB cache is not enabled on the site, the full-size original image will always be used.
Working with Image Renditions

Once image renditions have been configured on a site, site users working in a Site Assets library can edit
how each image rendition will appear by cropping the image as necessary to fit the dimensions of the
rendition.
Additional Reading: For more information on working with image renditions, read
SharePoint 2013 Design Manager image renditions on MSDN at
The settings associated with each rendition are stored as a comma-delimited string within the Property
Bag associated with each Image item in the Asset Library where they are stored. The string is comprised of
seven integer values, in the following order:
 Rendition Version
 Source Image Width

 Source Image Height
 Crop X Position
 Crop Y Position
 Crop Width
 Crop Height
When inserting or editing an image on a page, authors can select from the available renditions through
the SharePoint UI. Each rendition has an associated URL that can be used to link to the image. The
following is an example:
http://www.contoso.com/siteimages/contoso-logo.jpg?RenditionID=1
Each rendition has a unique numeric identifier that is used to select the appropriate rendition.
Alternatively, you can specify the specific height and width of the rendition, and SharePoint will match the
correct rendition if it exists, as follows:
http://www.contoso.com/siteimages/contoso-logo.jpg?Height=100&Width=100
If there are multiple renditions matching the same height and width, SharePoint will select the rendition
with the lowest ID value.
Note: Warning: If the Height and Width specified do not match an existing rendition, the
full-size image will be returned.
Using Content Delivery Networks

A Content Delivery Network (CDN) is a network of
servers distributed across multiple geographic
locations, and is designed to provide robust delivery
of static and streaming Internet content. When
requests for content are received by the CDN, they
are routed to servers in closest proximity to the
user. This minimizes network latency and optimizes
Internet bandwidth. This can result in faster page
load times for the static resources; for streaming
content, CDNs can help to provide smoother
playback.
The key benefits of CDNs include:
 Performance. Resources are delivered from servers in closer proximity to the user. Since content
hosted on a CDN is static, they also benefit from aggressive caching strategies.
 Reliability. Content delivery networks are most commonly hosted in professionally managed data
centers that provide strong security and high reliability.
 File Mirroring. Content is copied between multiple server locations, providing protection from
regional disasters and ensuring high availability.
 Scalability. CDNs can scale up quickly to support spikes in demand, and also provide service level
agreements for performance.
The use of a CDN for hosting static resources such as CSS, JavaScript, images, and video for public-facing
websites has become very popular in recent years. In addition to the benefits of listed above, A CDN also
off-loads having to serve static content from an organization’s web servers, which helps to maximize
resources for the generation of dynamic content.
Getting started with the benefits of a CDN is easy. There are a number of public CDNs hosting popular
open-source libraries that you can use right away. For example, the Microsoft Ajax Content Delivery
Network hosted at ajax.aspnetcdn.com hosts popular libraries like jQuery, jQuery UI, jQuery Mobile,
Knockout.js, and Twitter Bootstrap.
The following example shows how you can link jQuery from your website:
Sample Microsoft CDN jQuery Script Link

<script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-1.9.0.min.js"></script>
<script>
// fallback if CDN fails
(window.jQuery || document.write('<script src="/scripts/jquery-
1.9.0.min.js"><\/script>'));
</script>
Best Practice: Despite the implied high-availability of CDNs, in recent years there have
been some very public failures that have impacted the business operations of CDN customers. To
protect your site against potential CDN failures, it is a best practice to include fallback scripts to
local resources.
To support your own site-specific resources, you will need to select and sign up for a CDN that provides
hosting services. There are many CDN service providers, including the Microsoft Windows Azure Content
Delivery Network.
Reference Links: You can find out more information on the Windows Azure Content
Delivery Network on MSDN at http://go.microsoft.com/fwlink/?LinkId=205043
Demonstration: Creating and Configuring an Image Rendition

The instructor will now demonstrate how to work with image renditions. First, you will see how to enable
the BLOB cache in a development environment by editing the web.config file. Next, you will see how to
define image renditions by specifying a name, a width, and a height. Finally, you will see how to
customize how individual images are presented in each rendition.
Note: In production environments, you should avoid manually editing web.config files,
because it becomes hard to keep changes synchronized across multiple web servers. Instead, you
should use the SPWebConfigModification class to make the changes programmatically,
typically within a feature receiver class. For more information, see How to: Add and Remove
Web.config Settings Programmatically at http://go.microsoft.com/fwlink/?LinkID=311887. The
article was written for SharePoint 2010, but the process is the same in SharePoint 2013.
Demonstration Steps
the password Pa$$w0rd.
3. Open a File Explorer window and browse to C:\inetpub\wwwroot\wss\VirtualDirectories\80.
4. Right-click web.config, point to Open with, and then click Microsoft Visual Studio 2012.
5. In the web.config file, locate the BlobCache element.

6. Review the BlobCache element attributes:
o The location attribute specifies the file system location where files will be cached.
o The path attribute specifies the file types that should be cached, in the form of a regular
expression.
o The maxSize attribute specifies the maximum size of the cache in gigabytes (GB).
o The enabled attribute specifies whether the BLOB cache is enabled.
Note: The BLOB cache is already enabled in the virtual machine to save time during the
demonstration.
8. Open Internet Explorer and browse to http://www.contoso.com.
9. On the Contoso Pharmaceuticals home page, click Sign In.

10. On the Settings menu, click Site settings.
11. On the Site Settings page, under Look and Feel, click Image Renditions.
12. On the Image Renditions page, click Add new item.

13. On the New Image Rendition page, in the Name box, type Landscape Large.
14. In the Width box, type 500.
15. In the Height box, type 400, and then click Save.
16. On the Settings menu, click Site contents.
17. On the Site Contents page, click Site Collection Images.
18. On the Site Collection Images page, click new item.

19. In the Add a document dialog box, browse to E:\Democode\VanGoghStarryNight.jpg, click Open,
and then click OK.
20. In the Site Collection Images – VanGoghStarryNight.jpg dialog box, click Save.
21. On the Site Collection Images page, click All Assets.
22. On the All Assets page, select the VanGoghStarryNight row (click in the column with a checkmark
header).
23. On the ribbon, on the DESIGN tab, click Edit Renditions.
Note: Because you are viewing a newly-uploaded image, SharePoint may take
approximately a minute to generate the renditions.
24. Scroll down the page and briefly review how the image appears in each rendition.
25. Under the Landscape Large rendition, click Click to change.
26. Click OK in the Message from Webpage dialog box.
27. Drag the image handles to resize the selected area. Notice how the resolution stays the same, at 500 x
400 pixels, but you are effectively zooming in on the selected area.
28. Drag the selected area, and notice how the preview image is updated.
Note: The key point here is that the dimensions of the rendition do not change; in this case, they
are fixed at 500 x 400 pixels. However, for individual images, you can configure whether to scale the
whole image down to the size of the rendition, or whether to crop the image to size, or a combination of
the two.
29. Click Cancel, and then close Internet Explorer.

Lab: Optimizing SharePoint Publishing Sites

Scenario
The marketing team at Contoso wants to ensure that the public-facing website has been optimized for
Internet search engines. They are also concerned that the site is not performing as well as it could The
team has received feedback that many pages load slowly on mobile devices. The team has asked you to
configure SharePoint 2013. According to Administration policy, customization and configuration of
SharePoint must be done through either PowerShell or through SharePoint Features and Solutions.
Objectives
 Activate features required to support Sitemap generation.
 Work programmatically with SEO settings and properties.
 Configure SharePoint cache settings.
 Configure Image Renditions.
Lab Setup

Exercise 1: Optimizing a Site for Search Engines

Scenario
In this exercise you will optimize the site collection at www.contoso.com for Internet search engines. You
will be adding features to a SharePoint solution package to configure SEO settings and properties by
using the SharePoint server-side object model.
You will start by activating Sitemap generation and configuring Search Engine Sitemap Exclusions to
advise web crawlers to ignore the site’s legal notices. Next, you will configure the site to support website
identification for Microsoft Bing, and enable canonical URLs for the sites product catalog pages. Finally,
you will update the SEO properties on the site Welcome Page, and the Managed Navigation terms for
each of the site’s top level navigation landing pages.

1. Configure SEO Settings
2. Configure SEO Properties
3. Test the SEO Settings and Properties Features
 Task 1: Configure SEO Settings


3. Open the solution at E:\Labfiles\Starter\Contoso.Website.SEO\Contoso.Website.SEO.sln in Visual

Studio 2012.
4. Add a new Feature to the project and rename it to Settings.
5. Set the title of the Feature to Contoso.Website.SEO - Settings.
6. Set the scope of the Feature to Site.

7. Add an event receiver class to the Feature.
8. In the event receiver class, add using statements for the following namespaces:
o System.Text
9. Uncomment the FeatureActivated method.

10. Within the FeatureActivated method, add the following code:

{
}
Note: When calling the SPSite.RootWeb property, it is a best practice to utilize a using
statement to ensure the object instance is properly disposed of when complete.
For the remainder of this Lab, code should be appended within the using statement curly braces.
11. Within the FeatureActivated method, and within the SPWeb using statement, insert the contents of
the text file at E:\Labfiles\Starter\Snippets\ConfigureSEOSettings.txt.
12. Review the code you just added. The code performs the following tasks:
o It enables the sitemap generation feature.

o It configures the robots.txt file to exclude various file paths from search crawling.
o It adds Bing web identification meta tags to all pages.
o It enables canonical URLs for the Product Catalog pages.
13. Build your solution and verify that the build completes without errors.
 Task 2: Configure SEO Properties

1. Add a new Feature to the project and rename it Props.
2. Set the title of the Feature to Contoso.Website.SEO - Props.
o Microsoft.SharePoint.Utilities

7. Within the FeatureActivated method, add the following code:

{
}
8. Within the FeatureActivated method, and within the SPWeb using statement, insert the contents of
the text file at E:\Labfiles\Starter\Snippets\ConfigureSEOProperties.txt.
o It updates the welcome page with SEO properties.
o It adds custom SEO properties to the Navigation term set.
11. Save your work.
 Task 3: Test the SEO Settings and Properties Features

1. Start the project without debugging.
2. When the Contoso Pharmaceuticals page has finished loading, if you are not already signed in, click
Sign In.
3. Browse to the site collection Features, and activate the following Features:
o Search Engine Sitemap
o Contoso.Website.SEO – Props
o Contoso.Website.SEO – Settings
4. Browse to the search engine optimization settings for the site collection.
5. Verify that the SEO settings include a msvalidate.01 meta tag to validate your ownership of the site.
6. Verify that category is configured as a filter link parameter for canonical URLs.
7. Browse to the search engine sitemap settings for the site collection.
8. Verify that items on the /legal/ path are excluded from indexing by Internet search engines.
9. Browse to the site home page, and then edit the page.
11. Verify that the SEO properties have been updated and are not blank.
12. Click Cancel.
13. From the Page tab on the ribbon menu, click Check In, and then click Discard Check Out.
Results: After completing this lab, the Internet-facing site collection at www.contoso.com configuration
for search engine optimizations should be complete.
Exercise 2: Maximizing the Performance of a Publishing Site

Scenario
In this exercise you will optimize the site collection at www.contoso.com to improve performance. You will
be adding features to a SharePoint solution package to configure caching and image renditions by using
the SharePoint server-side object model.
You will start by configuring the BLOB Cache settings, which requires modifying the web.config of a
SharePoint web application through code. Next, you will configure the Page Output cache settings for the
Contoso website site collection. Lastly, you will configure a new image rendition that can be used for
inserting masthead images on the site.

1. Configure BLOB Caching
2. Configure Page Output Caching
3. Configure Image Renditions

4. Test the Performance Features
 Task 1: Configure BLOB Caching

1. Open the solution at E:\Labfiles\Starter\Contoso.Website.SEO\Contoso.Website.Perf.sln in Visual
Studio 2012.
2. Add a new Feature to the project and rename it BlobCache.
3. Set the title of the Feature to Contoso.Website.Perf – BLOB Cache.
4. Set the scope of the Feature to WebApplication.
6. In the event receiver class, add a using statements for the Microsoft.SharePoint.Administration
namespace.
8. Within the FeatureActivated method, insert the contents of the text file at
E:\Labfiles\Starter\Snippets\ConfigureBlobCache.txt.
o It modifies the web.config file for the web application to enable the BLOB cache.
o It changes the maximum size of the BLOB cache on disk to 5GB.
11. Save your work.
 Task 2: Configure Page Output Caching

1. Add a new Feature to the project and rename it OutputCache.
2. Set the title of the Feature to Contoso.Website.Perf – Output Cache.
5. In the event receiver class, add a using statements for the Microsoft.SharePoint.Publishing
namespace.
E:\Labfiles\Starter\Snippets\ConfigureOutputCache.txt.
o It creates a new cache profile on the publishing web.

o It enables and configures the page output cache settings for the site collection.
10. Save your work.
 Task 3: Configure Image Renditions

1. Add a new Feature to the project and rename it ImageRenditions.
2. Set the title of the Feature to Contoso.Website.Perf – Image Renditions.

o Microsoft.SharePoint.Publishing
o System.Linq
o System.Linq.Expressions

E:\Labfiles\Starter\Snippets\ConfigureImageRenditions.txt.
o It creates a new image rendition named Masthead.
o It adds the new image rendition to the collection of image renditions on the root web.
10. Save your work.
11. Right-click the project, and then click Deploy.
 Task 4: Test the Performance Features

1. Open the Central Administration website, and verify that the Contoso.Website.Perf – BLOB Cache
feature is active on the Host Named Site Collection (HNSC) Host Web Application web
application.
3. In Visual Studio 2012, open the web.config file for the web application on port 80.
4. Locate the BlobCache element. Verify that the Enabled attribute is set to true and the maxSize
attribute is set to 5.
6. In Internet Explorer, browse to http://www.contoso.com. Sign In if necessary.
7. Browse to the page output cache settings for the site collection.
8. Verify the output cache is enabled, that the Anonymous Cache Profile has been set to Contoso
Anonymous, and that the Authenticated Cache Profile has been set to Disabled.
9. Browse to the image renditions settings for the site, and verify that an image rendition named
Masthead has been added.
will be configured for performance optimizations.

In this module, you learned about various features and techniques that you can use to optimize the
performance of an Internet-facing SharePoint site. You learned about how to configure your site for
optimal performance in external search engines. You also learned about various techniques you can use to
improve the performance of your Internet-facing sites, typically by minimizing the amount of data that is
sent back and forth between the browser and the SharePoint server.
Review Question(s)
Question: What is the purpose of the robots.txt file? How is it configured in SharePoint?
Test Your Knowledge

Question
Which type of SharePoint cache is targeted at static resources such as image files?
Page Output Cache
BLOB Cache
Distributed Cache
Session State
Page Cache
Statement Answer
Can the use of canonical URLs improve search

engine ranking?
Test Your Knowledge

Question
Which optimization technique describes combining multiple source files into a single file?
Minification
Bundling
Image Renditions
Minimal Download Strategy (MDS)
Page Output Caching

9-1
Module 9
Working with Business Connectivity Services
Contents:
Module Overview 9-1
Lesson 1: Business Connectivity Services in SharePoint 2013 9-2
Lesson 2: Creating BDC Models in SharePoint Designer 9-11
Lesson 3: Creating BDC Models in Visual Studio 2012 9-23
Lab: Working with Business Connectivity Services 9-30
Module Overview
Most organizations store information in a variety of disparate systems. In many cases, these organizations
want to be able to view, interact with, and update information from these disparate systems from a single
interface. This reduces the need for information workers to constantly switch between systems and creates
opportunities for power users or analysts to aggregate data from multiple sources.
In Microsoft® SharePoint® Server 2013, Business Connectivity Services (BCS) is a collection of

technologies that enable you to query, view, and update data from external systems. In this module, you
will learn how to develop BCS solutions.
Objectives
 Describe the key components of Business Connectivity Services in SharePoint Server 2013.
 Create and configure Business Data Catalog (BDC) models by using SharePoint Designer.
 Create and configure BDC models by using Microsoft Visual Studio® 2012.
9-2 Working with Business Connectivity Services
Lesson 1
Business Connectivity Services in SharePoint 2013
In SharePoint 2013, BCS relies on interactions among a variety of components. To create a BCS solution
effectively, you must have a solid understanding of the roles performed by each of these components and
how they work together to provide access to external data. In this lesson, you will learn about the core
components of BCS and how to consume external data.
Lesson Objectives
After completing this lesson you will be able to:
 Describe the purposes and capabilities of BCS.
 Describe the high-level architecture of BCS.
 Describe the use of external content types.
 Describe the types of external data accessed by BCS.

 Describe how to consume external data.
Overview of Business Connectivity Services

In SharePoint 2013, BCS is a set of components that
enable you to work with data that resides outside of
SharePoint. BCS enables you to support the full
range of create, retrieve, update, delete, and query
(CRUDQ) data operations on external data sources
from SharePoint and from Microsoft Office client
applications.
When you connect to external data sources through

BCS, you can work with the data in a variety of
ways. For example, you can
 Use the built-in Business Data Web Parts to

display, query, and interact with the data.
 Create external lists that enable you to interact with external data in a similar way to standard
SharePoint list data.
 Use the Search service to index and query the data.

 Use the data to augment user profiles.
 Use the data to drive SharePoint workflows.
 Interact with the data from Office client applications.

 Create custom-coded SharePoint solutions that use the BCS object model to support more esoteric
scenarios.
BCS service applications

SharePoint includes two service applications that underpin the functionality of BCS:
 The BDC service application. This service application stores and manages BDC models. BDC model
data is stored in the BDC Metadata Store, and contains information used to access external systems to
execute CRUDQ operations on external content types.
 The Secure Store service application. This service application enables you to map SharePoint users to
external system credentials. For example, you could map a group of SharePoint users to a set of
Microsoft SQL® Server credentials that provide access to a specific database.
BDC Runtime
The BDC runtime retrieves information from the BDC Metadata Store and uses that information to
connect to the external system and to execute operations based on the data stored in the BDC Metadata
Store and the request received from a client application. The BDC runtime establishes a connection to the
external data store by using the Connector Framework, and acts as a data access layer between the
external system and the client application.
Connector Framework
The Connector Framework receives requests from the BDC Runtime and manages a connection to the
external system based on the information provided by the BDC runtime. All data filtering and sorting
requested by the client application is done at the connector level, before the data is sent to the client
application. There are four connectors available out-of-the-box that can be used:
 SQL. Allows access to SQL Server databases.

 WCF. Allows access to WCF data services.
 .NET Assembly. Uses a custom .NET Assembly created by a developer to access data.
 OData. Allows access to OData services.
Additional Reading: For more information on the core components of BCS in SharePoint
Server 2013, see Overview of Business Connectivity Services in SharePoint 2013 at
BDC Model Files and Schema

BCS uses BDC models to represent data entities
within an external system. The BDC model is a self-
contained, XML-based file that provides SharePoint
with all the information it needs to connect to and
interact with external data. This information
includes:
 Details of how to connect to and authenticate

to the external system.
 Definitions for each data entity of interest on

the external system.
 Definitions for each CRUDQ data access

method that you want to perform against data entities.
A BDC model is portable. You can export it and import it. You can create BDC models for the following
types of data sources:
 SQL Server databases.
 Windows Communication Foundation (WCF) web services.
 Open Data Protocol (OData) web services.
 Other types of data source, by using a .NET connectivity assembly.
You can create BDC models interactively in SharePoint Designer for SQL Server databases and WCF web
services. For OData web services and other types of data source, you can use Visual Studio templates to
create and develop the model.
A BDC model contains all the information required to connect to an external source and perform data
operations. A BDC model consists of the following components:
 External system. Each BDC model can contain one or more external systems, which are represented by
LobSystem elements in the BDC model file. An external system is a general representation of an
external data source, such as a SQL Server database with specific tables.
 System instance. Each external system can include one or more system instances, which are
represented by LobSystemInstance elements in the BDC model file. As the name suggests, a system
instance represents a specific instance of an external system—for example, an instance of your SQL
Server database hosted on a specific server with specific security settings. The system instance
includes connection details, such as the web service endpoint or the SQL Server connection string,
and details of how to authenticate to the external system instance.
 Entities. Each external system can include one or more entities, which are represented as external
content types (ECTs).
BDC Model File

A BDC model file is an XML file with an extension of .bdcm (for BDC model). The bdcm file contains
several elements, describing different aspects of the model. The first element in the BDC model file is the
Model element. The Model element contains basic information about the model, such as its name and
the schema file used for the model.
The following code shows an example of a BDC Model element:
The BDC Model Element

<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<Model xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.microsoft.com/windows/2007/BusinessDataCatalog
BDCMetadata.xsd"
Name="ContosoDW"
xmlns="http://schemas.microsoft.com/windows/2007/BusinessDataCatalog">
Note: The BDCMetadata.xsd file used as the schema for BDC models can be found in the
Xml\Schemas folder in the installation folder for Visual Studio, or the TEMPLATE\XML folder In
the SharePoint hive.
Just below the Model element, you will find the AccessControlList element, containing the access
control entries for the BDC model.
The following code shows an example AccessControlEntry element:
The BDC AccessControlEntry Element

<AccessControlList>
<AccessControlEntry Principal="contoso\administrator">
<Right BdcRight="Edit" />
<Right BdcRight="Execute" />
<Right BdcRight="SetPermissions" />
<Right BdcRight="SelectableInClients" />
</AccessControlEntry>
</AccessControlList>
<AccessControlList>
The different rights available for a BDC model are:
 Edit. Allows users to execute operations that change the data in the external system.
 Execute. Allows users to execute, or read, data from the external system.
 SetPermissions. Allows users to manage access control entries for the BDC model.
 SelectableInClients. Allows users to view external data in client applications that consume the BDC
model.
Below the access control list, you will find the LobSystems element. The LobSystems element contains a
list of LobSystem elements, representing different data connections and containing the necessary
information to connect to the external system.
The following code shows an example LobSystem element:
The LobSystem Element

<LobSystems>
<LobSystem Type="Database" Name="ContosoDW">
<LobSystemInstances>
<LobSystemInstance Name="ContosoDW">
<Properties>
<Property Name="AuthenticationMode"
Type="System.String">WindowsCredentials</Property>
<Property Name="DatabaseAccessProvider"
Type="System.String">SqlServer</Property>
<Property Name="RdbConnection Data Source" Type="System.String">LON-
SP1</Property>
<Property Name="RdbConnection Initial Catalog"
Type="System.String">ContosoRetailDW</Property>
<Property Name="RdbConnection Integrated Security"
Type="System.String">SSPI</Property>
<Property Name="RdbConnection Pooling" Type="System.String">True</Property>
<Property Name="SsoProviderImplementation"
Type="System.String">Microsoft.Office.SecureStoreService.Server.SecureStoreProvider,
Microsoft.Office.SecureStoreService, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c</Property>
<Property Name="SsoApplicationId" Type="System.String">BDCAPP01</Property>
<Property Name="ShowInSearchUI" Type="System.String"></Property>
</Properties>
</LobSystemInstance>
</LobSystemInstances>
In the example above, you can see that the external system is a SQL Server database named
ContosoRetailDW hosted on a server named LON-SP1, and that authentication settings are stored in the
Secure Store Service in SharePoint.
The LobSystem element also contains a list of Entity elements, defining each external content type. The
example below contains one entity, or external type, named Employee. There are two methods in the
Employee entity:
 A method of type Finder named DimEmployeeReadList.
 A method of type SpecificFinder named DimEmployeeReadItem.
In the full contents of the file you would be able to see the actual SQL code used to retrieve both a list of
employees and a single employee.
The following code shows the example Employee entity:
The Entity Element

<Entities>
<Entity Namespace="urn:sharepoint.contoso.com:contosodw"
Version="1.0.0.0"
EstimatedInstanceCount="10000"
Name="Employees"
DefaultDisplayName="Employees">
<AccessControlList>…</AccessControlList>
<Identifiers>
<Identifier TypeName="System.Int32" Name="EmployeeKey" />
</Identifiers>
<Methods>
<Method IsStatic="false" Name="DimEmployeeReadList">
…
<MethodInstance Type="Finder" ReturnParameterName="DimEmployeeReadList"
Default="true" Name="DimEmployeeReadList" DefaultDisplayName="Employees Read List">
<Properties>
<Property Name="UseClientCachingForSearch"
Type="System.String"></Property>
<Property Name="RootFinder" Type="System.String"></Property>
</Properties>
</MethodInstance>
</MethodInstances>
</Method>
<Method IsStatic="false" Name="DimEmployeeReadItem">
…
<MethodInstances>
<MethodInstance Type="SpecificFinder"
ReturnParameterName="DimEmployeeReadItem"
ReturnTypeDescriptorPath="DimEmployeeReadItem[0]" Default="true"
Name="DimEmployeeReadItem" DefaultDisplayName="Read Item Employees">
<Properties>
<Property Name="LastDesignedOfficeItemType"
Type="System.String">None</Property>
</Properties>
</MethodInstance>
</MethodInstances>
</Method>
</Methods>
</Entity>
</Entities>
</LobSystem>
</LobSystems>
</Model>
Introduction to External Content Types

An ECT is essentially a model of a data entity. ECTs
are central to how users work with external data in
SharePoint and in Office client applications. For
example, when you create an external list, you
associate it with an ECT. When you create Business
Data Web Parts, you select an ECT. Each ECT defines
the following components:
 One or more identifiers that uniquely identify

instances of the external data entity.
 One or more methods that define CRUDQ
operations on the external data entity, together
with any sorting and filtering criteria.
External content types are usually based on tables or views in a database, on methods in a WCF or OData
service, or on entities in a .NET assembly. Depending on the type of object your ECT is based on, it may
have a limited set of operations. The full list of operations, or methods, that an ECT can have is:
 Create. Used to create a new entity in the external system. For instance, in a database table this could
be achieved by using an INSERT statement.
 Finder. Used to retrieve a list of entities from the external system. For instance, in a database table this
could be achieved by using a SELECT statement.
 SpecificFinder. Used to retrieve a single entity from the external system. For instance in a database
table, this could be achieved by using a SELECT statement with a WHERE clause filtering by the
primary key.
 Update. Used to modify an entity in the external system. For instance, in a database table this could
be achieved by using an UPDATE statement.
 Delete. Used to delete an entity from the external system. For instance, in a database table, this could
be achieved by using a DELETE statement.
Note: SharePoint Designer uses friendly names for these stereotyped operations. Most
notably, the Finder operation is named ReadList in SharePoint Designer and the SpecificFinder
operation is named ReadItem.
Besides operations, ECTs contains one or more fields. Fields can be compared to columns in a SharePoint
list or database table. Fields are defined as TypeDescriptor elements in the BDC model file, and contain
the following properties:
 Name. Name of the field.
 TypeName. Data type for the field, such as System.String or System.Int32.
 Size. Used for string types to specify the number of characters.
 RequiredInForms. Boolean property used to specify if the field is to be displayed on edit, update, and
create forms.
 ShowInPicker. Boolean property used to specify if the field is to be displayed when end users are
selecting an instance of the ECT in custom list.
ECT Scope
In SharePoint 2010, all external content types created were scoped to the farm. Farm-scoped ECTs are
available for use in any Web Application, site collection, or site within a SharePoint farm. A user must have
sufficient permissions on the BDC metadata store to deploy an external content type.
In SharePoint 2013, ECTs can be scoped to a single app. Apps contain all the resources they need to run in
an isolated area. App-scoped ECTs provide access to external data within a SharePoint app.
Note: App-scoped ECTs can only use OData connections.
Introduction to External Systems

External systems are represented in a BDC model by
the LobSystemInstance element. Each external
system in a BDC model can use one, and only one,
connection to an external source. There are four
types of connections that an external system can
use:
 SQL Server. Allows connectivity to a SQL Server

database. When using a SQL Server connection,
each ECT in the external system is represented
by a table, view, or stored procedure returning
the output of a SELECT clause.
 WCF Web Service. Allows connectivity to a WCF

service. When using a WCF service, each ECT is represented by a Data Contract in WCF, and data for
the ECT is retrieved by using a WCF operation.
 OData. Allows connectivity to an OData service. When using an OData service, each ECT is
represented by an OData entity, and data is retrieved by using OData operations.
 Custom .NET Assembly. Allows connectivity to custom .NET classes. When using a custom .NET
assembly, ECTs are represented as .NET classes, and accessed by methods created in the assembly.
This type of connection allows access to any data source, as long as the developer is able to create
code in .NET to access the data.
The following code shows an example of a LobSystemInstance element that uses a SQL Server
connection:
The LobSystemInstance Element

<Properties>
<Property Name="DatabaseAccessProvider" Type="System.String">SqlServer</Property>
<Property Name="RdbConnection Data Source" Type="System.String">NYC-DB1</Property>
<Property Name="SsoApplicationId" Type="System.String">ChangeMe</Property>

</Properties>
The main use of an external system (or LobSystemInstance) is to specify how authentication and
authorization will be performed when connecting to the external data source. Depending on the external
system being accessed, you will need to work together with the external system administrator to
determine how to allow users to access the system while promoting the least privileges principle. You will
either map a group of users of the BCS solution to a single account on the external system, or create a
one-to-one mapping of individual users of the BCS solution and accounts in the external system. The
account information for the external system can be stored and managed by the Secure Store Service. The
Secure store service stores all data related to accounts in an encrypted format in a SQL Server database.
Demonstration: Exploring a BDC Model File

The instructor will now briefly explore the structure of a BDC model file in Visual Studio.
Demonstration Steps
1. Connect to the 20489B-LON-SP-09 virtual machine. If you are not already logged on, log in as
CONTOSO\Administrator with password Pa$$w0rd.
2. On the Start screen, type Visual Studio, and then click Visual Studio 2012.
3. On the FILE menu, point to Open, and then click File.

4. In the Open File dialog box, browse to E:\Setupfiles, click ContosoDW.bdcm, and then click Open.
5. Note the message stating that the BDC Model Designer only supports editing models with a single
.NET LobSystem. The ContosoDW.bdcm file models a SQL Server connection.
6. In the BDC Explorer pane, expand the ContosoDW node.
7. Right-click the uppermost ContosoDW node, and then click Properties.
8. In the Properties pane, in the drop-down list box at the top of the pane, notice that the name
includes the text Model. This indicates that the node represents the top-level Model element of the
BDC model.
9. In the BDC Explorer pane, click the second ContosoDW element.
10. In the Properties pane, in the drop-down list box at the top of the pane, notice that the name
includes the text LobSystem. This indicates that the node represents the LobSystem element of the
BDC model.
11. In the BDC Explorer pane, expand the second ContosoDW element, and then expand the
LobSystemInstances element.
12. Notice that the model includes a single LobSystemInstance element named ContosoDW. Explain
that this defines properties for a specific instance of an external system, such as connection strings
and authentication settings.
13. Expand the Employees node. This represents an ECT.
14. Notice that the ECT contains two methods: a ReadItem method and a ReadList method.
15. On the ContosoDW.bdcm tab, click XML Editor.
16. In the Microsoft Visual Studio dialog box, click Yes.

17. Briefly review the XML content of the ContosoDW.bdcm file. Try to relate the elements in the XML
file to the structure you explored in the BDC Explorer pane.
Consuming External Data

ECTs can be used in SharePoint in different ways,
based on the scope of the ECT.
 Farm-scoped ECTs can be accessed by using an

external list in any SharePoint site or in business
data web parts, or be used as a column type in
any custom list.
 App-scoped ECTs can be accessed only by apps
that include the ECT.
When accessing data by using an ECT in an external

list, certain list settings are mapped to ECT
methods. For instance, the Finder method is used
by default to populate the list, the SpecificFinder method is used to populate the edit form for a given
item in the list, and the Updater method is used to modify an item from the update form for the item.
Besides that, filters created for the ECT can be configured in the list settings for the external list.
ECTs can also be accessed by using one of the following business data web parts:
 Business Data List. Displays a list of items from an ECT.
 Business Data Related List. Displays a list of items from an ECT that are related to a parent ECT.
Requires an association.
 Business Data Item. Displays a single item from an ECT.
 Business Data Item Builder. Creates an ECT item based on parameters from a URL string and provides
it to other Business Data Web Parts.
 Business Data Actions. Displays actions for an ECT item.
 Business Data Connectivity Filter. Filters the content of a connected Business Data Web Part by using a
list of values from an ECT.
When used in a custom list, an ECT is treated as a column type. When adding an item to the custom list,
users can retrieve a list of entities and view all fields in the ECT that have the ShowInPicker property set
to True in the BDC model.
Lesson 2
Creating BDC Models in SharePoint Designer
SharePoint Designer can be used to create and deploy external systems by using connection to a SQL
Server database, WCF Service, or .NET Assembly. Once a data connection is created for the external
system, you can add ECTs and define filters, associations, and permissions.
Lesson Objectives
At the end of this lesson, you will be able to:
 Configure external systems connections.
 Implement external content types.

 Configure actions.
 Create profile pages.
 Create external lists.
Configuring External System Connections

External system connections are used to specify
how the BCS runtime connects to an external
system when executing CRUDQ operations for
external content types available in the system.
There are three types of external system
connections you can configure by using SharePoint
Designer:
 SQL Server. SQL Server connections can be used

to access a database server and retrieve data
from tables, views, or stored procedures. When
creating a SQL Server connection, you need to
specify the following properties:
o Database server. Name of the server hosting the database to be accessed.
o Database Name. Name of the database hosting the data to be accessed.
 WCF Service. WCF Service connections can be used to access data by using a WCF Service. The WCF
Service must implement methods used to execute CRUDQ operations on the data being accessed.
When creating a WCF Service connection, you need to specify the following properties:
o Service Metadata URL. URL used to retrieve the WCF Service metadata.
o Metadata Connection Mode. The method used to retrieve metadata.

 Web Service Description Language (WSDL). Uses WSDL to retrieve service metadata.
 Metadata Exchange. Uses metadata exchange to retrieve metadata.
o Service Endpoint URL. URL for the WCF Service endpoint.
 .NET Type. .NET Type connections are used to access data by using a custom .NET assembly. The
assembly must contain classes defining the different external content types available, and methods
used to execute CRUDQ operations on the data exposed by the assembly. When creating a .NET Type
connection, you need to specify the following property:
o Assembly System. The custom assembly created to expose data. The assembly must be added to
the Global Assembly Cache before you can see it in SharePoint Designer.
Note: .NET Type connections require a custom assembly developed by using Visual Studio.
We will cover the use of Visual Studio later in this module.
The following code example shows how a SQL Server connection is represented in a BDC model file:
BDC Connection to SQL Server

<Properties>
<Property Name="DatabaseAccessProvider" Type="System.String">SqlServer</Property>
<Property Name="RdbConnection Data Source" Type="System.String">NYC-DB1</Property>
<Property Name="SsoApplicationId" Type="System.String">ChangeMe</Property>
</Properties>
Configuring External System Authentication

When you use SharePoint Designer to configure a
connection to a WCF service or a SQL Server
database, you must specify the authentication
settings for your connection. SharePoint Designer
presents you with the following options:
 User’s Identity. This option essentially specifies

pass-through authentication. The BDC runtime
uses the identity of the caller to authenticate to
the external system. The identity of the caller is
typically the SharePoint user who invoked the
operation, unless the call is invoked by code
running with elevated privileges.
 Impersonated Windows Identity. This option relies on the Secure Store Service to supply Windows
credentials with which to authenticate to the external system.
 Impersonated Custom Identity. This option relies on the Secure Store Service to supply custom
credentials with which to authenticate to the external system.
 BDC Identity. This option is also known as RevertToSelf authentication. The BDC runtime uses the
identity of the IIS application pool that runs the BDC service application to authenticate to the
external system.
Each of these options has advantages and disadvantages.

Using Pass-Through Authentication

When you select User's Identity, the BDC runtime impersonates the identity of the caller. While this
approach may be useful in small deployments and test environments, it does not always scale well. Pass-
through authentication has the following disadvantages:
 Every user or account that will invoke calls to external data must have individually assigned
permissions on the back-end system.
 Your environment must be configured for Kerberos. In an NTLM environment, the double-hop
limitation will prevent the BDC runtime from impersonating the caller.
In most cases, configuring the Secure Store Service provides a more manageable alternative to using pass-
through authentication.
Using the Secure Store Service

When you select Impersonated Windows Identity or Impersonated Custom Identity, you are
indicating that you want the Secure Store Service to provide credentials with which to authenticate to the
external system.
The Secure Store Service maps the identities of SharePoint users to the credentials that should be used to
access a specific external system. These mappings are organized in target applications. Typically, you
create a Secure Store target application for each external system to which you want to authenticate. When
you configure a BDC model to use Impersonated Windows Identity or Impersonated Custom
Identity, you specify a Secure Store target application ID that uniquely identifies the target application
that you want to use with your external system.
You can configure a Secure Store target application to use two types of credential mappings:
 Individual. The identities of individual SharePoint users are mapped to individual external system
credentials.
 Group. The identities of a group of SharePoint users are mapped to a single set of external system
credentials.
In most cases, using a group mapping is the most convenient solution, because you only need to
configure a single set of permissions on the external system. If you need more granular control over
permissions on the external system, or you need to be able to audit access to the external system, you will
need to use an individual mapping instead.
Using RevertToSelf Authentication

When you select BDC Identity, the BDC runtime authenticates to the external system by using the
application pool identity associated with the BDC service application. You should use this approach with
caution, since the application pool runs with a highly privileged set of permissions. As a general guideline,
Microsoft recommends that you do not use RevertToSelf authentication in a production environment.
Because of the security risks inherent in using RevertToSelf authentication, you must configure the BDC
service application to support RevertToSelf before you can configure your BDC models to use it.
Additional Reading: Before you consider enabling RevertToSelf authentication in a

production environment, review the guidance at Business Connectivity Services security operations
(SharePoint Server 2010) at http://go.microsoft.com/fwlink/?LinkId=328965. The article was
written for SharePoint 2010, but the concepts apply equally to SharePoint 2013.
You can use the following PowerShell commands to enable RevertToSelf authentication in a development
environment:
Enabling RevertToSelf Authentication

$bdcServiceApp = Get-SPServiceApplication | where {$_ -match "<Name of BDC Service
Application>"
$bdcServiceApp.RevertToSelfAllowed = $true
Implementing External Content Types

Once an external connection is created, one or
more external content types can be created. To
create an ECT you must define the name of the
external content type, along with its fields and
operations. Each operation will contain output
and/or input parameters. Some of these parameters
might be used as filters for the operation.
Operations
There are five operations that can be created for an
external content type. These operations can be
mapped back to methods in a WCF Service or .NET
Type connection, or statements in a SQL Server
connection:
 ReadItem. Also referred to as Specific Finder. This operation is used to retrieve a single item from the
ECT based on a key. This is a required operation.
 ReadList. Also referred to as Finder. This operation is used to retrieve a list of items from the ECT. This
is a required operation.
 Create. This operation is used to create a new instance of an item in the ECT. In SQL Server
connections it maps to a stored procedure or INSERT statement.
 Update. This operation is used to modify an existing instance in the ECT.
 Delete. This operation is used to delete an existing instance in an ECT.

The following code shows an example ReadList operation:
A ReadList Operation
<Method IsStatic="false" Name="EmployeeReadList">
<Properties>
<Property Name="RdbCommandType"
Type="System.Data.CommandType, System.Data, Version=4.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089">Text</Property>
<Property Name="RdbCommandText"
Type="System.String">SELECT TOP(@EmployeeKey) [EmployeeKey] , [FirstName] ,
[LastName] , [EmailAddress] , [DepartmentName]
FROM [dbo].[Employee] ORDER BY
[EmployeeKey]</Property>
<Property Name="BackEndObjectType" Type="System.String">SqlServerTable</Property>
<Property Name="BackEndObject" Type="System.String">DimEmployee</Property>
<Property Name="Schema" Type="System.String">dbo</Property>
</Properties>
By looking at the RdbCommandText property, you can see the actual SELECT statement used to retrieve
a list of employees from the external system by using a SQL Server connection.
Note: The TOP clause in the sample XML above represents a filter.
Identifiers
Each ECT must have a unique identifier. On SQL Server connections, unique identifiers are usually mapped
to primary keys on a table or view, and are represented in the Entity element as an Identifier child
element.
The following code shows an example Identifier element:
The Identifier Element

<Entity Namespace="urn:sharepoint.contoso.com:contosodw"
Version="1.0.0.0" EstimatedInstanceCount="10000"
Name="Employees" DefaultDisplayName="Employees">
<Identifiers>
<Identifier TypeName="System.Int32" Name="EmployeeKey" />
</Identifiers>
Filters
Filters can be created in the ReadList operation to filter the data brought back from the external system.
There are five types of filter that can be created by using SharePoint Designer:
 Comparison. Used to filter data based on a comparison, similar to a WHERE clause in a SQL
statement.
 Limit. Used to filter data by specifying the maximum number of rows retrieved from the external
system, similar to a TOP clause in a SQL statement.
 Page Number. Used to retrieve a set number of items and provide pagination for an ECT. Also similar
to a TOP clause in a SQL statement. You cannot configure a Limit and a Page Number filter in the
same operation.
 Timestamp. Used to retrieve data based on a time field. All items that have a timestamp greater than
the input parameter are retrieved.
 Wildcard. Used to retrieve data based on a comparison that may contain wildcards. Similar to a
WHERE clause with a LIKE operator in a SQL statement.
The XML below shows a sample limit filter.
The following code shows an example of a limit filter:
A Limit Filter
<FilterDescriptors>
<FilterDescriptor Type="Limit" FilterField="EmployeeKey" Name="Filter">
<Properties>
<Property Name="UsedForDisambiguation" Type="System.Boolean">false</Property>
<Property Name="IsDefault" Type="System.Boolean">false</Property>
<Property Name="CaseSensitive" Type="System.Boolean">false</Property>
</Properties>
</FilterDescriptor>
</FilterDescriptors>
Input and Output Parameters

Parameters are used to define data sent to different operations (input parameters) and returned by
operations (output parameters).
The following code shows an example of an input parameter for a filter on a ReadList method:
An Input Parameter
<Parameters>
<Parameter Direction="In" Name="@EmployeeKey">
<TypeDescriptor TypeName="System.Int64" AssociatedFilter="Filter" Name="EmployeeKey">
<DefaultValues>
<DefaultValue MethodInstanceName="DimEmployeeReadList"
Type="System.Int64">100</DefaultValue>
</DefaultValues>
</TypeDescriptor>
</Parameter>
Output parameters are usually more complex, since operations are used to retrieve not a single value, but
an individual item that may contain multiple fields or a collection of such items. The XML below shows a
sample output parameter for a ReadList operation:
The following code shows an example of an output parameter for a ReadList operation:
An Output Parameter
<Parameter Direction="Return" Name="EmployeeReadList">
<TypeDescriptor TypeName="System.Data.IDataReader, System.Data, Version=4.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089" IsCollection="true"
Name="DimEmployeeReadList">
<TypeDescriptors>
<TypeDescriptor TypeName="System.Data.IDataRecord, System.Data, Version=4.0.0.0,
Culture=neutral, PublicKeyToken=b77a5c561934e089" Name="EmployeeReadListElement">
<TypeDescriptors>
<TypeDescriptor TypeName="System.Int32" ReadOnly="true"
IdentifierName="EmployeeKey" Name="EmployeeKey">
<Properties>
<Property Name="ShowInPicker" Type="System.Boolean">true</Property>
</Properties>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="FirstName">
<Properties>
<Property Name="Size" Type="System.Int32">50</Property>
<Property Name="RequiredInForms" Type="System.Boolean">true</Property>
</Properties>
<Interpretation>
<NormalizeString FromLOB="NormalizeToNull" ToLOB="NormalizeToEmptyString"
/>
</Interpretation>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="LastName">
<Properties>
<Property Name="RequiredInForms" Type="System.Boolean">true</Property>
</Properties>
<Interpretation>
<NormalizeString FromLOB="NormalizeToNull" ToLOB="NormalizeToEmptyString"
/>
</Interpretation>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="EmailAddress">
<Properties>
</Properties>
<Interpretation>
<NormalizeString FromLOB="NormalizeToNull" ToLOB="NormalizeToNull" />
</Interpretation>
</TypeDescriptor>
<TypeDescriptor TypeName="System.String" Name="DepartmentName">
<Properties>
</Properties>
<Interpretation>
<NormalizeString FromLOB="NormalizeToNull" ToLOB="NormalizeToNull" />
</Interpretation>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
</Parameters>
Associations
Associations can be compared to relationships in a database. They can describe either one-to-many
relationships, or many-to-many relationships. However, many-to-many relationships cannot be created by
using SharePoint Designer; they must be manually added to the BDC model file.
One-to-many associations (or forward associations, or simply associations) are created in SharePoint
Designer from the entity containing the foreign key (or many side of the relationship).
A reverse association is used to navigate from the many side of a one-to-many relationship to the one
side. Reverse associations are rarely used, since they are not needed for navigation in Business Data Web
Parts when an association is already available. Also, reverse associations can only be created by using
stored procedures in a SQL Server connection, or by using a method in a WCF Connection.
The following code shows an example association between two ECTs:
A BDC Association
<Association Name="SalesChannelAssociation" Type="AssociationNavigator"
ReturnParameterName="SalesChannelAssociation" DefaultDisplayName="Sales Channel
Association">
<Properties>
<Property Name="ForeignFieldMappings" Type="System.String"><?xml version="1.0"
encoding="utf-16"?>
<ForeignFieldMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ForeignFieldMappingsList>
<ForeignFieldMapping ForeignIdentifierName="ChannelKey"
ForeignIdentifierEntityName="Channel"
ForeignIdentifierEntityNamespace="http://sharepoint.contoso.com" FieldName="channelKey"
/>
</ForeignFieldMappingsList>
</ForeignFieldMappings></Property>
</Properties>
<AccessControlList>
<AccessControlEntry Principal="contoso\administrator">
<SourceEntity Namespace="http://sharepoint.contoso.com" Name="Channel" />
<DestinationEntity Namespace="http://sharepoint.contoso.com" Name="Sales" />
</Association>
Note: There will be other elements related to the association in the BDC model file, such as
a method describing the association, and a type descriptor for the association foreign key in the
“many” external content type.
Configuring Actions and Profile Pages

Items exposed through external content types can
be viewed by using a profile page, and have tasks
executed based on its data by using actions.
Profile Pages
Profile pages are special pages in a pre-determined

SharePoint site that can be used to view
information about an item from an external content
type. One of the main advantages of using a profile
page is that existing associations for an item are
automatically populated in a profile page. Profile
pages can be edited and are used by default as an
action for external content types. To use a profile
page, you must execute the following steps:
1. Create a site in SharePoint.
2. Configure the BCS service to use the site created in step 1 as the profile site.
3. Create a Profile Page for each external content type.
Actions
External content types can be associated with one or more actions. Actions are links that end users can
click to execute a task that can consume data from an ECT item. Any ECT field or combination of fields
can be used as parameters for the action. For instance, if an external content type contains information
about employees, and one of the fields is the employee’s email address, an action can be used to
compose an email to the employee by using the mailto: protocol and the email address of the employee
as a parameter. Another example would be to open the employee’s profile by using the http: protocol
and the user name as a parameter. Here are some sample actions you can use:
 Email
o URL: mailto:{0}
o Parameter {0}: email address
 Display map
o URL: http://www.bing.com/maps/?v=2&where={0},{1},{2},{3}
o Parameter {0}: address
o Parameter {1}: city
o Parameter {2}: state
o Parameter {3}: postal code
Creating External Lists

Depending on the operations available for the
content type, external lists can be used to display,
modify, delete, and create items for an external
content type. External lists provide a mechanism for
allowing access to external content types from a
SharePoint site.
There are two ways of creating external lists for a

content type.
 From SharePoint Designer. Once you create an
external content type in SharePoint Designer,
you can create an external list by simply
clicking on Create Lists & Form on the Lists &
Forms section of the EXTERNAL CONTENT TYPE ribbon. When creating an external list by using this
method, you can specify whether to use InfoPath forms for the view, edit, and create forms for the
list.
 From a SharePoint site. You can add an external list as an app to any SharePoint site, and when doing
so, select the external content type to be used. Once the list is created, you can view and edit the list
settings in the same way that you would manage a regular list. One of the main differences on the
settings for external lists is that you will be able to see and configure any filter created on the external
content type.
Demonstration: Creating and Consuming an External Content Type

In this demonstration, you see how to:
 Create a secure store target application to connect to external data sources.
 Create an external content type in SharePoint Designer.
 Create an external list in SharePoint Designer.
 Set permissions on an external content type in Central Administration.
 Browse data in an external list.
Demonstration Steps
1. On the Start screen, type SQL Server Management Studio, and then press Enter.
2. In the Connect to Server dialog box, click Connect.

3. In Object Explorer, expand Security, expand Logins, and then double-click

CONTOSO\Administrator.
4. Explain that you are going to use the Administrator account to access the external database, so you
first need to grant the account the required permissions in SQL Server.
5. In the Login Properties - CONTOSO\Administrator dialog box, under Select a page, click User
Mapping.
6. Under Users mapped to this login, select ContosoRetailDW.
7. Under Database role membership for: ContosoRetailDW, select db_datareader, and then click
OK.
8. Close SQL Server Management Studio.
9. On the Start screen, type Central Administration, and then press Enter.
10. On the Central Administration home page, under Application Management, click Manage service
applications.
11. On the list of service applications, click Contoso Secure Store Service Application.
12. Explain that you are now going to create a secure store target application that you will use to connect
to the external database.
13. On the ribbon, in the Manage Target Applications group, click New.
14. In the Target Application ID box, type ContosoDWApp.
15. In the Display Name box, type Contoso Retail Data Warehouse.
16. In the Contact E-mail box, type administrator@contoso.com.
17. In the Target Application Type drop-down list box, click Group, and then click Next.
18. Leave the field names and field types unchanged and click Next.
19. In the Target Application Administrators box, type CONTOSO\Administrator.
20. In the Members box, type Everyone, and then click OK.
21. Explain that you have created a group target application that maps all users to a single set of
credentials. You will now set the credentials that the target application will use to connect to the
external database.
22. In the list of target applications, select ContosoDWApp.
23. On the ribbon, in the Credentials group, click Set.
24. In the Set Credentials for Secure Store Target Application (Group) dialog box, in the Windows
User Name box, type CONTOSO\Administrator.
25. In the Windows Password and Confirm Windows Password boxes, type Pa$$w0rd, and then click
OK.
27. On the Start screen, type SharePoint Designer, and then press Enter.
28. In SharePoint Designer, click Open Site.
29. In the Open Site dialog box, in the Site name box, type http://sharepoint.contoso.com, and then
click Open.
30. If you are prompted for credentials, log in as CONTOSO\Administrator with password Pa$$w0rd.
SharePoint Designer may take some time to open the site.
31. When SharePoint Designer has finished loading the site, in the Navigation pane, click External
Content Types.
32. On the ribbon, in the New group, click External Content Type.
33. In the External Content Type Information pane, in the Name row, click New external content
type.
34. Type Account, and then press Tab.
35. In the External System row, click Click here to discover external data sources.
36. Click Add Connection.
37. In the External Data Source Type Selection dialog box, in the Data Source Type drop-down list
box, click SQL Server, and then click OK.
38. In the SQL Server Connection dialog box, in the Database Server box, type LONDON.
39. In the Database Name box, type ContosoRetailDW.
40. Click Connect with Impersonated Windows Identity.
41. In the Secure Store Application ID box, type ContosoDWApp, and then click OK.
42. In the BCS Secure Store : ContosoDWApp dialog, log in as CONTOSO\Administrator with
password Pa$$w0rd.
43. On the Data Source Explorer tab, expand ContosoRetailDW, and then expand Tables.
44. If a dialog box displays the error message Cannot complete refresh, this because BCS does not
support some of the columns in the database. Click OK.
45. Right-click DimAccount, and then click Create All Operations.

46. In the All operations dialog box, click Next.
47. On the Parameters page, in the Data Source Elements list, clear ParentAccountKey,
AccountLabel, Operator, CustomMembers, ValueType, CustomMemberOptions, ETLLoadID,
LoadDate, and UpdateDate.
48. Click AccountKey, and confirm that Map to identifier is checked.
49. Click AccountName, and then select Show In Picker.

50. Click AccountType, and then select Show In Picker.
51. Click Next.
52. On the Filter Parameters page, click Finish.

53. Explain that having created an external content type, you will now create an external list to display
data from the external content type.
54. On the ribbon, in the Lists & Forms group, click Create Lists & Form.
55. In the Save Confirmation dialog box, click Yes.
56. In the Create List and Form for Account dialog box, in the List Name box, type Accounts, and then
click OK.
57. On the ribbon, in the Views group, click Summary View.
58. Notice that the External Lists pane now includes a list named Accounts.
59. Close SharePoint Designer.

60. The final high-level step is to grant users permission to use the external content type you have
created. On the Start screen, type Central Administration, and then press Enter.
applications.
62. On the list of service applications, click the Contoso Business Data Connectivity Service
Application link.
63. On the ribbon, in the Permissions group, click Set Metadata Store Permissions.
64. In the Set Metadata Store Permissions, type Administrator, and then click Add.
65. Under Permissions for CONTOSO\Administrator, select all four permissions.
66. Select Propagate permissions to all BDC Models, External Systems and External Content Types
in the BDC Metadata Store, and then click OK.
67. In the list of external content types, select Account.
68. On the ribbon, in the Permissions group, click Set Object Permissions.
69. In the Set Object Permissions dialog box, type Everyone, and then click Add.
70. Under Permissions for Everyone, select Execute and Selectable In Clients, and then click OK.
71. In the Internet Explorer address bar, type http://sharepoint.contoso.com, and then press Enter.
73. When the page has finished loading, on the Quick Launch navigation menu, click Accounts.
74. Verify that the Regions list retrieves and displays a set of data from the external database.
Lesson 3
Creating BDC Models in Visual Studio 2012
The ease of use of SharePoint Designer makes it a valuable tool for developers and SharePoint power
users. Users can now create external content types without developer knowledge or experience. However,
there are several limitations to SharePoint Designer that can be overcome only by using Visual Studio
2012. OData connections cannot be made by using SharePoint Designer, and any external content type
created in SharePoint Designer is scoped to the entire farm. .NET connector assemblies must also be
created programmatically. To overcome these limitations, you can create ECTs directly in Visual Studio,
and have them deployed to the farm or to a single SharePoint app.
Lesson Objectives
 Describe the use of the BDC Model Designer.

 Connect to an OData source.
 Create app-scoped BDC models.
 Create an external list by using an app-scoped BDC model.

 Configure apps to display external lists.
Using the BDC Model Designer

You can use the BDC Model Designer to create
more complex BDC Models that require custom
code to execute the different operations available
for an external content type. The Business Model
Designer is composed of the following tools:
 BDC Designer. The BDC Designer surface is

used to manage entities in an external system
in a visual manner. From the surface you can:
o Add entities to the BDC model
o Delete entities from the BDC model
o Define associations between entities
 BDC Method Details Pane. The BDC Method Details Pane is used to define parameters, instances, and
filters for a given method. You can create the following types of methods from the BDC Method
Detail Pane:
o SpecificFinder. Specific Finder, or Read Item, methods are used to retrieve a single instance of the
entity based on its identifier. They contain two parameters:
 id. The id parameter is an input parameter used to send the identifier of the instance to be
retrieved.
 returnParameter. The return parameter represents the instance of the external content type
being returned by this method. Its data type must be the data type used to define the entity.
o Finder. Finder, or Read List, methods are used to retrieve a list of instances from the external
content type. By default, there is only one parameter for these methods:
 returnParameter. The return parameter represents a collection of the external content type
being returned by this method.
Note: You should consider using filters for finder methods to restrict the number of
instances returned by a single operation. You can have multiple instances of this method for
different retrieval operations. For instance, when dealing with an employee content type, you
could have a finder method instance to retrieve all employees, another to retrieve all employees
in a given office, and another to retrieve all employees under a given manager.
 Creator Method. Creator methods are used to create a new instance of an external content type. By
default, they contain the following parameters:
o ReturnParameter. The return parameter should use the entity class as its return type.
o newEntity. The new entity parameter should have the same data type as the return parameter.
You need to be sure that if the identifier property of the entity is marked as Read-Only in the
definition of the data type in the BDC Designer, you mark the identifier in this method as NOT
read-only.
 Updater Method. Updater methods are used to modify the properties of a given instance of the
external content type. They contain a single parameter:
o Entity. The entity parameter must be of the same data type as the entity definition, and must
have its identifier set to NOT read-only.
 Deleter Method. Deleter methods are used to delete an instance of the external content type. They
contain a single parameter:
o Identifier. The identifier parameter is an input parameter that represents the unique identifier of
the instance to be deleted.
 BDC Explorer. The BDC Explorer displays a hierarchical view of the model, with all its entities,
methods, and properties.
To create a BDC model and an external content type by using the BDC Model Designer, execute the
following steps:
1. Create a new empty SharePoint Solution in Visual Studio 2012.
2. Add a new item of type Business Data Connectivity Model (Farm Solution only) to the empty
project.
3. In Solution Explorer, rename the Entity1.cs file to the name of the entity you want to create. An
entity represents an external content type.
4. In the renamed file, define the properties of the new entity. Properties represent fields in your
external content type.
5. In BDC Explorer, rename the Entity1 entity to the name of the entity being created, and rename its
identifier to the name of the property in the new entity that will be used for an identifier.
6. In BDC Explorer, rename the parameters for the ReadItem and ReadList methods to map back to the
properties of your new entity.
7. In the BDC Method Details pane, create any other necessary operations, such as Creator, Deleter, and
Updater.
8. If necessary, fix the parameters for the new methods in BDC Explorer.
9. Right-click an operation in BDC Explorer and click View Code to view the method created for the
operation.
10. Implement the necessary methods.
11. Deploy the solution to a SharePoint farm.

12. From Central Administration, set the permissions for the new external system.
Connecting to OData Sources

One of the limitations of using SharePoint Designer
for the creation of external content types is that you
cannot connect to an OData data source from an
external content type created in SharePoint
Designer. If you need to access an OData data
source to populate an external content type, you
must do so by creating an external content type in
a SharePoint app. One of the advantages of
creating an external content type this way is that
you do not need to deploy the content type to a
farm, but rather access it from individual SharePoint
apps. These types of external content types are
referred to as app-scoped external content types.
OData is a standard used to expose data from any data source such as a database by using an URL, thus
allowing for a simplified way to connect to data sources within a network.
OData uses HTTP, Atom, and JavaScript Object Notation (JSON) to empower developers to create
solutions that communicate with any data source. SharePoint uses a new OData connector to allow
communication by using the OData protocol.
BCS can use the OData connector to expose OData data sources as external content types without having
to write any code, other than the OData service itself.
To create an app-scoped external content type, execute the following steps:
1. Create new SharePoint-Hosted app.
2. Right-click the project, in the Add submenu click Content Types for an External Data Source, and
then follow the wizard to add an OData connection and entities.
Once entities have been added by using the OData connector, you can view their XML definition by right-
clicking the .ect file created for the entity, clicking Open With, and then selecting the XML Editor.
The following code shows an example association created automatically by the OData connector:
An OData Connector Association

<Association Name="GetCategoryFromProducts" Type="AssociationNavigator"
ReturnParameterName="@Category" ReturnTypeDescriptorPath="Category">
<AccessControlList>
<AccessControlEntry
Principal="STS|SecurityTokenService|http://sharepoint.microsoft.com/claims/2009/08/isauth
enticated|true|http://www.w3.org/2001/XMLSchema#string">

<SourceEntity Namespace="NorthwindModel" Name="Products" />
<DestinationEntity Namespace="NorthwindModel" Name="Categories" />
</Association>
Creating App-Scoped BDC Models

External content types added to a SharePoint app
by using the OData connector are always app-
scoped. The external content type is not available to
the entire SharePoint farm; it is only available to the
app that created it.
After creating an app-scoped external content type,

you can publish your SharePoint app in Visual
Studio to create an .app package. The package is a
single file with an extension of .app, but it uses the
same Open XML format used by other Microsoft
applications. That means you can rename the file
with a .zip extension to view its contents. When you
do that, you will notice that the .zip file contains a file of type .wsp, which is used to deploy SharePoint
solutions. This is also a package file, but it uses .cab technology. If you rename the .wsp file as a .cab file,
you will be able to see the contents of the .wsp package. Within the .wsp file you will find a file of type
.bdcm. This is the BDC Model created by the OData connector. This is a fully functional BDC Model and
can even be deployed to a SharePoint farm as a farm-scoped BDC Model, extending the use of OData
beyond app-scoped external data types.
Additional Reading: For more information on how to convert an app-scoped BDC model
to farm-scoped model, see How to: Convert an app-scoped external content type to tenant-scoped
at http://go.microsoft.com/fwlink/?LinkId=321942.
Security Credentials
BCS supports authentication to OData services by using one of the following authentication modes:
 PassThrough. Pass-through authentication is used to pass the credentials of the user accessing the
external content type to the OData service. Pass-through authentication cannot be used in
environments where two-factor authentication is used, since it can only pass the username and
password to the OData service. Consider using pass-through for testing environments.
 RevertToSelf. Revert-to-self authentication uses the credentials of the application pool used to run
SharePoint for authentication.
 Windows Credentials. Windows credentials authentication uses a Windows account to authenticate

with the OData service. When using Windows credentials, you can store the account information in
the Secure Store Service and associate it with a target application id, and refer to this id in the BDC
model.
 Digest Credentials. Digest credentials are not stored in the Secure Store Service. Digest Credentials are
composed of username and password, and use the Message Digest encryption algorithm to secure
the user information while on the network.
 Credentials. You can use credentials authentication for custom identities. A custom identity might
contain several pieces of information, such as username, password, and application id. You can store
custom identity information in the Secure Store Service in the same manner as Windows credentials.
 Custom Authentication using OData Extension Provider. You can also create your own custom
extension provider by inheriting from the ODataExtensionProvider and implementing you own
code for authentication.
Additional Reading: For more information on authentication modes, see Available

Authentication Modes at http://go.microsoft.com/fwlink/?LinkId=321943.
The XML segments below show the authentication settings for an OData service used by a BDC Model.
The following code shows example authentication settings for an OData-based BDC model:
Authentication Settings for an OData Service

<LobSystem Name="ContosoODataSource" Type="OData">
<Properties>
<Property Name="ODataServiceMetadataUrl"
Type="System.String">http://services.odata.org/Northwind/Northwind.svc/$metadata</Propert
y>
<Property Name="ODataServiceMetadataAuthenticationMode"
Type="System.String">PassThrough</Property>
<Property Name="ODataServicesVersion" Type="System.String">2.0</Property>
</Properties>
<LobSystemInstance Name="ContosoODataSource">
<Properties>
<Property Name="ODataServiceUrl"
Type="System.String">http://services.odata.org/Northwind/Northwind.svc</Property>
<Property Name="ODataServiceAuthenticationMode"
Type="System.String">PassThrough</Property>
<Property Name="ODataFormat" Type="System.String">application/atom+xml</Property>
<Property Name="HttpHeaderSetAcceptLanguage" Type="System.Boolean">true</Property>
</Properties>
The first segment shows the authentication and connection settings used to retrieve the OData service
metadata. The second segment contains the settings to access the actual service.
Deploying App-Scope Models

App-scoped BDC models are installed as part of the app provisioning process when you deploy an app for
SharePoint.
Creating External Lists from App-Scoped BDC Models

Users create external lists to access data from
external content types. When you create external
content types by using the OData connector in
Visual Studio 2012, the connector automatically
creates an external list for each external content
type generated. You can disable this behavior when
you run the SharePoint Customization Wizard to
add an OData source by unchecking the Create list
instances for the selected data entities (except
Service Operations) option.
The following code shows the contents of an

elements.xml file for an external list:
Element Manifest for an App-Scoped External List

<ListInstance Url="Lists/Territories" Description="Territories" OnQuickLaunch="TRUE"
Title="Territories">
<DataSource>
<Property Name="LobSystemInstance" Value="ContosoODataSource" />
<Property Name="EntityNamespace" Value="NorthwindModel" />
<Property Name="Entity" Value="Territories" />
<Property Name="SpecificFinder" Value="ReadSpecificTerritory" />
<Property Name="MetadataCatalogFileName" Value="BDCMetadata.bdcm" />
</DataSource>
</ListInstance>
</Elements>
If you need to manually create a new list instance for an app-scoped external data type, you must add a
new list instance to your project and change its elements.xml file manually by using the following
properties:
 LobSystemInstance. Name of the Lob system instance defined in the BDC Model file. If you created
the data source by using the OData connector, this is the name of the data source you created.
 EntityNamespace. Namespace for the entity. This information is retrieved from the OData metadata.
You can also get the namespace by opening the associated .ect file for the external content type in
the XML editor and looking for the Name attribute in the Model element.
 Entity. Name of the external content type.
 SpecificFinder. Name of the method used as a specific finder. You can also find this information in the
associated .ect file for the external content type.
 MetadataCatalogFileName. Name of the BDC Model file. The auto-generated name in Visual Studio is
BDCMetadata.bdcm. You can find this information in the elements.xml file for the OData data
source.
Configuring Apps to Display External Lists

A SharePoint-Hosted app that contains an external
list can be configured to display the list in different
ways:
 AppManifest.xml. You can change the startup

page for the app in the AppManifest.xml file to
point to an external list. That way, when you
run the app, the external list is displayed. The
XML fragment below shows the content of a
sample AppManifest.xml file.
The following code shows a sample of an

AppManifest.xml file that specifies an external list as
the start page:
Specifying an External List as a Start Pager

<Properties>
<Title>ContosoOData</Title>
<StartPage>~appWebUrl/Lists/Categories?{StandardTokens}</StartPage>
</Properties>
 Default.aspx. You can customize the Default.aspx for the app to use app parts to display the contents
of the external list.
 User navigation. Users can navigate to the external lists by changing the URL in their browser, using
the Quick Launch menu, or navigating to the list from the contents of the site.
Lab: Working with Business Connectivity Services

Scenario
Contoso has a database named ContosoRetailDW that contains data used for sales analysis and inventory
management. Managers want to enable users in the Sales department to view a list in a SharePoint site of
regions in which Contoso conducts business, and the associated customers in each of these regions.
Your task is to create a farm-scoped BDC Model to access data from the ContosoRetailDW database. You
will deploy the BDC model and test the model by creating sample pages to display a list of regions with a
corresponding list of customers.
In addition, managers want to enable better overview of the product inventory in selected parts of the
business. The IT department has developed an OData web service to expose parts of the database that are
used for inventory management. You will develop an App that includes a second BDC model, by using the
OData web service, that enables users to interact with the inventory management system through external
lists in SharePoint. The IT department will distribute the App to relevant departments within the business.
Objectives
In this lab, you will be able to:
 Create farm-scoped external content types by using SharePoint Designer.

 Create app-scoped external content types for OData web services.
Lab Setup
Exercise 1: Creating Farm-Scoped External Content Types

Scenario
Contoso has a database named ContosoRetailDW that contains data used for sales analysis. They want to
allow users from the Sales department to view a list of regions in which Contoso conducts business, and
the associated customers in each of these regions from a SharePoint site.
1. Configure SQL Server and the Secure Store Service to Manage Authentication for BCS
2. Create the Geography ECT
3. Configure a Filter for the Geography ECT
4. Create the Customer ECT
5. Create an Association
 Task 1: Configure SQL Server and the Secure Store Service to Manage Authentication
for BCS
1. Use SQL Server Management Studio to map the CONTOSO\Administrator user to the
ContosoRetailDW database with the db_datareader permission.
3. Use the Central Administration web site to create a new Secure Store Target Application with the
following properties:
Property Value
Application ID ContosoDWGeographyApp
Display Name Contoso Retail Geography Data Warehouse
Contact email administrator@contoso.com
Target Application Type Group
Application administrators CONTOSO\Administrator
Application members Everyone
4. Set the credentials for the ContosoDWGeographyApp target application to use the username
CONTOSO\Administrator, with the password Pa$$w0rd.
 Task 2: Create the Geography ECT

1. Use SharePoint Designer to connect to the http://sharepoint.contoso.com site by using the
username CONTOSO\Administrator, and the password Pa$$w0rd.
2. Create a new external content type by using the following parameters:
o Name: Geography
3. Create a new external system connection by using the following parameters:
o Data Source Type: SQL Server
o SQL Server name: LONDON

o Database name: ContosoRetailDW
o Connection name: ContosoRetailDWConnection
4. Configure the ContosoRetailDWConnection connection to use an impersonated identity by using

the Secure Store Application with the ID ContosoDWGeographyApp.
5. Use the DimGeography table in the database to create all operations for the Geography ECT. You
should use all elements as parameters, except ETLLoadID, LoadDate and UpdateDate. You should
map the GeographyKey element to the identifier, and you should include the following properties in
the picker:
o ContinentName
o CityName
o StateProvinceName
o RegionCountryName
6. Create an external list to display the Geography ECT named Regions.
7. Use the Central Administration web site to grant all permissions on the metadata store for the
Geography ECT to members of the CONTOSO\Domain Admins security group.
8. Grant the Execute and Selectable in clients permissions on the Geography object to the Everyone
security group.
9. Use Internet Explorer to browse to the http://sharepoint.contoso.com site, and then view the
Regions list. Verify that SharePoint displays data from the database correctly.
 Task 3: Configure a Filter for the Geography ECT

1. Configure a filter for the Read List operation for the Geography ECT by using the following
parameters:
o Data Source Element: RegionCountryName
o Name: ByCountry
o Type: Comparison
o Operator: Equals
o Filter Field: RegionCountryName
o Use to create match list in external item picker: true
o Default Value: United States
2. View the external list.

3. Change the filter to display all regions in China.
 Task 4: Create the Customer ECT

1. Open SharePoint Designer and connect to the http://sharepoint.contoso.com site.
2. Create a new ECT by using the following parameters:
o Name: Customer
o Connection: ContosoRetailDWConnection
3. Select the DimCustomer table from the database, and then create the ReadItem operation for the
Customer ECT by using the following parameters:
o Name: ReadCustomer
o Display Name: Read Single Customer
o Identifier: CustomerKey
o Return parameters: CustomerKey, GeographyKey, Title, FirstName, LastName, EmailAddress
4. Create the ReadList operation for the Customer ECT by using the following parameters:
o Name: ReadCustomers
o Display Name: Read Customer List
o Filter parameters: limit the number of items returned to 100 by default.

o Return parameters: CustomerKey, GeographyKey, Title, FirstName, LastName, and

EmailAddress.
o Show in picker: FirstName and LastName.
5. Create an external list for the Customer ECT named Customers.
6. View the new external list, and verify that the list displays customer data.
 Task 5: Create an Association

1. In SharePoint Designer, create an association between the Customer and the Geography external
content types by using the following parameters:
 Name: CustomerGeographyNavigation
 Display Name: Customer Geography Navigation
 External Content Type: Geography
 Foreign key (and identifier): GeographyKey
 Return parameters:
o CustomerKey
o GeographyKey
o Title
o FirstName
o LastName
o EmailAddress
2. Save your work and close SharePoint Designer.

3. Open Internet Explorer and browse to the site at http://sharepoint.contoso.com.
4. Create a new web part page named CustomersByCountry.
5. On the CustomersByCountry page, add a Business Data List web part by using the following
parameters:
o Location: Left Column
o Type: Geography
6. Filter the contents of the list to show only regions in the Australia.
7. Add a Business Data Related List web part by using the following parameters:
o Location: Middle Column
o ECT: Customer
o Relationship: Customer Geography Association
8. Connect the Customer List to the Geography List.

9. Stop editing the page.
10. View the list of customers in Bendigo (click the double-arrow icon next to GeographyKey 425).

Results: After this exercise, you should have created two external content types named Geography and
Customer, exposed their data by using external lists and business data web parts.
Exercise 2: Creating App-Scoped External Content Types

Scenario
Contoso has access to an OData service on the web that is used for managing product inventory and
reordering. You need to create an app-scoped external content type to read data from the OData service.
1. Start the OData Service
2. Create a SharePoint-Hosted App
3. Interacting with Business Data by Using External Lists
 Task 1: Start the OData Service

1. In Visual Studio 2012, open the solution at
E:\Labfiles\Starter\ContosoODataService\ContosoODataService.sln.
2. In the ContosoODataWebServcice.svc file, review the InitializeService method. Notice that this
method exposes the DimProducts, DimProductCategories and DimProductSubcategories entities.
These map to the DimProduct, DimProductCategory and DimProductSubcategory database
tables.
3. Start the solution without debugging. You should leave this service running because you will use it in
the following tasks.
 Task 2: Create a SharePoint-Hosted App

1. In a new instance of Visual Studio, create a SharePoint hosted app with the following settings:

o Name: ContosoOData
o Locations: E:\Labfiles\Starter
2. Configure the new app to use http://dev.contoso.com for debugging, and to deploy the app as a
SharePoint-Hosted app.
3. Add an OData connection by using the following parameters:
o OData URL: http://localhost:12345/ContosoODataWebService.svc/
o Name: ContosoODataSource
4. Create an external content type for the following entities:
o DimProductSubcategories
o DimProducts
5. Create external lists for the content types.
6. Explore the DimProducts external content type. Note that the content type includes an association
between the DimProducts and DimProductSubcategories entities.
7. Explore the DimProducts list instance.
8. Modify the List URL to Lists/Products.

9. Review the Elements.xml file that defines the DimProducts list. Notice that the file defines a
connection to the external OData source.
 Task 3: Interacting with Business Data by Using External Lists

1. Configure the ContosoOData app to use the DimProducts list as its start page.
2. Start the app in debugging mode.
3. Review the properties for the product with a ProductKey with the value 1.
4. Change the description for the product to New description.
6. Open SQL Server Management Studio.
7. In the ContosoRetailDW database, in the dbo.DimProduct table, view the top 1,000 rows. Verify
that the ProductDescription for row 1 has been updated to New description.
Results: After this exercise, you should have created two app-scoped external content types named
Product and Category by using an OData connection.
Question: You need to create an external content type to expose data from a SQL Server
database. The content type must be used in multiple Web Applications within your
SharePoint farm. What type of external content type would you create? What tool would you
use to create the ECT with the least amount of coding effort?
Question: You need to create an external content type to expose data from a custom data
source. The custom data source uses a binary file format documented by the developers who
created it. What tools would you use to create the ECT?
Question: You need to create an external content type to expose data from an OData
service created by another developer. What type of ECT would you create?

In this module, you learned about Business Connectivity Services in SharePoint 2013. First, you learned
about the core components of Business Connectivity Services, primarily about the Business Data
Connectivity application and the Secure Store Service application. Next, you learned how to create and
work with BDC models in both SharePoint Designer 2013 and Visual Studio 2012.
10-1
Module 10
Creating Advanced Business Data Connectivity Models
Contents:
Module Overview 10-1
Lesson 1: Configuring BDC Models for Search 10-2
Lesson 2: Developing Custom Connectivity Components 10-9
Lesson 3: Working with External Events and Notifications 10-16
Lab: Creating and Deploying a .NET Connectivity Assembly 10-30
Module Overview
Out-of-the-box search connectors provide many features that enable you to index common sources such
as file shares, Microsoft® SharePoint® sites, and web sites. However, there are many times when you
must index a non-common source such as a proprietary database or an in-house custom data store with
proprietary interfaces. When you are faced with these situations, it is important to know the tools that
SharePoint Business Connectivity Services (BCS) offers to index these complex sources of structured and
unstructured data. This module will explore how to create custom search connectors by using several
methodologies. You also will be shown the advanced SharePoint 2013 external event notification feature
that supports SharePoint list features such as alerts and event receivers when external data changes.
Objectives
 Describe BCS Connector Framework scenarios.
 Design and Develop BCS Connector stereotyped operations
 Design and Configure Business Data Connectivity (BDC) model security.
 Optimize Search Connector crawl performance.

 Use Visual Studio® to build BDC Models for Search
 Deploy BDC Search connectors.
 Debug and troubleshoot your search connectors.

 Design and deploy BDC event subscriber methods.
 Describe how to format event notification messages.
 Configure alerts and event receivers on external lists.

10-2 Creating Advanced Business Data Connectivity Models
Lesson 1
Configuring BDC Models for Search
In this lesson, you will learn to extend SharePoint Search to index external data sources by using BDC
models. You will also learn to implement best practices when it comes to multi-part items such as security,
metadata, and file stream indexing.
Lesson Objectives
 Decide when to use BDC models to extend search.
 Describe the BCS Connector Framework.

 Describe and implement BDC search stereotyped operations.
 Configure BDC model properties for search.
 Configure custom item level security.
 Utilize techniques to optimize search indexing.
Searching External Data

When searching data that lives outside SharePoint,
users expect a single interface from which to submit
queries. SharePoint provides two ways to do this.
 Federated Search. This method enables
SharePoint to send the search query to the
remote system that has indexed the content
and let it return results. This has the advantage
of not having to download the remote content
and thus use CPU, memory, and disk space on
the SharePoint Search server. The drawbacks to
this method are that the external system must
implement a known protocol such as
SharePoint, Exchange, or OpenSearch 1.0/1.1, and the results do not use a common relevance-
ranking model and won’t be ordered properly when viewing results together.
 Content Crawling. Content is indexed by SharePoint by using a connector, and search queries are
presented from the SharePoint search servers. This allows you to base the results on relevance-
ranking models, define how and when the content is indexed, and back up the index results locally.
SharePoint indexing connectors are implemented by using protocol handlers or Business Connectivity
Services connectors. These indexing connectors know how to connect, what to crawl, and how to crawl a
remote source. BCS connectors allow SharePoint to connect to any number of external systems and to
utilize those systems in several different ways throughout SharePoint sites. By using BCS to index external
data, users can submit search queries against that indexed data through the SharePoint Search APIs. BCS
provides several types of connectors for connecting to these external data sources, including simple
database connectivity, WCF, .NET, and Custom.
Connector Components
Each connector is made up of two major components, these include:
 BDC Model file. This file defines the structure of the data, the operations that need to be called, and
the connection information.
 Connector Code. This is the main part of the Connector. This code fetches the remote data and
remotes it back to the search crawler for processing by the content processing components
As you learned in other modules, BCS utilizes the concept of a metadata store to hold the BDC model file,
or definition, of the external data source. As a review, these metadata models have the following major
pieces of information:
 Connectivity information. How to connect to an external system.
 Entity information. The structure of the data; for example, the columns in the table of a database.
 Operations. The methods used to access entity information, such as database SQL statements or the
web methods in a web service.
BCS Indexing Connectors

There are two categories of connectors: Line of Business Data and Custom Repository. Line of Business
Data connectors execute based on internal code provided by SharePoint and only require a BDC Model
file. Custom Repository connectors require both the model file and custom code. You will learn more
about these connectors in a subsequent lesson.
Note: In earlier versions of SharePoint, the task of extending search capabilities was done
by using protocol handlers built mainly in C++.
Connector Design
There are four important pieces of information that each BCS connector must have. They are:
 Connectivity. The connector must define how to get to the content. This can be via basic TCP/IP or file
system operations. When implementing a TCP/IP protocol, you must know the specific application
level data formats (such as HTTP, FTP, SMTP, simple sockets, and so forth). You should implement the
connectivity by using best practices and that you don’t have any unhandled exceptions that will
prevent the crawler from processing all the content. This layer will also implement any security that is
required to authenticate to the target source.
 Structure of repository. After you have connected to a content source, you can navigate the content
that is in that source. You can list the containers (such as folders) and the items in those containers
(such as files).
 Incremental crawls. When crawling external sources, your connector should be intelligent enough to
determine when items have changed and when they have not. This can optimize the time it takes to
index the external data.
 Securing data. How you read and apply security information to a set of crawled items when pulling
from a custom external source.
Tools
There are several tools provided by Microsoft to create BDC models that use custom connectors. The tools
include SharePoint Designer and Visual Studio. SharePoint Designer can be used to create the BDC model
based on several different types of connectors, including database, WCF, and .NET. SharePoint Designer
has limited functionality and does not provide the ability to implement custom logic for the methods; you
can only do this through Visual Studio. You can use SharePoint Designer to export models, which you can
then import into a BCS service application by using the Central Administration web site.
Enhancements in 2013
Several enhancements were made to the connector framework in 2013, including:
 The retrieval of claims information for content in external sources.
 Improved exception capturing and logging for troubleshooting.
BDC Search Methods

Each BCS Connector BDC model must have a set of
stereotyped methods (also called operations)
defined on it. In relation to search, some are
required and others are optional. Each method type
has a specific role it must play in the connector
framework. The search-related stereotyped
methods include:
 Finder. A required operation that retrieve the

list of items that must be indexed.
 SpecificFinder. A required operation that
retrieves a single instance of any item from the
external source.
 IdEnumerator. This method returns all items that exist in the target data source.
 ChangedIdEnumerator. This method will tell the search crawler which items have changed and must
be re-indexed. It is optional but highly recommended that you implement this method.
 DeletedIdEnumerator. This method will tell the search crawler what items have been deleted and must
be re-indexed. It is optional to implement.
 BinarySecurityDescriptorAccessor. This method is responsible for building the security information for
an item. This information is then used to hide items in the search results to which the user does not
have access.
 StreamAccessor. This downloads the binary of the content that must be indexed. Most commonly, this
would the file binary.
BDC Model Search Properties

In addition to defining the BDC methods, you can
add extra search related properties that control the
search crawler at runtime. There are several
properties related to search defined at various levels
in the BDC Model, these include:
 ShowInSearchUI. Determines if the model

should be shown on the search content source
page.
 InputUriProcessor. Used to navigate the URLs

that are passed to the search crawler that will
then be used to find items to index.
 OutputUriProcessor. Used to generate the URLs that will be given to items indexed by a custom
connector.
 SystemUtilityTypeName. This property is used to point to the custom class and assembly that will
implement a custom connector.
 Title. Specifies the title of the external content type to display in search results.
 DefaultLocale. Used to specific the language. Can be overridden by the LCIDField or CultureField
properties.
 RootFinder. Applied to a method to support search (required unless you implement search by using
an IDEnumerator).
 DirectoryLink. Tells search to navigate the entity associations.

 DeletedCountField. A deleted count value; must be greater than zero to be used.
 WindowsSecurityDescriptorField. Used to tell search which field in the returned crawled properties
contains the ACL information.
 AuthorField. Used to tell search what crawled property is the author field.
 DisplayUriField. Used to tell search what crawled property is the URL that users will click in a search
result.
 LastModifiedTimeStampField. Tells search what crawled property is the modify date.
 DescriptionField. Tells search what crawled property is the description field.
 LCIDField. Used to tell search what crawled property will determine the language the item is in.
 CultureField. Used to specify the culture for the description field.
 Extension. The file name extension for the crawlable stream, the default is .txt.
 MimeType. Used to tell search what type of file the binary stream is. This overrides the Extension
property.
 UseClientCachingForSearch. If set on a Finder or IdEnumerator, the values will be cached and a

SpecificFinder will not be called.
 CrawlStartTime. The start time of the last crawl.
 SynchronizationCookie. Used to tell the external content source what time the last crawl was
completed for use in the ChangedIdEnumerator and DeletedIDEnumerator.
Note: In order for your BDC model to show up for use in Search Service Applications, you
must set at least the ShowInSearchUI property. You should also provide either the RootFinder
property or implement an IDEnumerator method.
BDC Model Search Security

Every connector must provide details about how to
connect to the external data source. This also
includes the security information about how it will
login to the target source. As you learned in
previous modules, there are several ways that
authentication can be set up for BCS connectors,
including:
 PassThrough
 RevertToSelf
 WindowsCredentials
 Credentials
 RDBCredentials
 DigestCredentials
When the target system is using NTLM, you can choose to use PassThrough authentication for crawling. If
the target external application uses Windows authentication, then PassThrough is often the most
appropriate authentication option. However, profile pages may require you to use the Secure Store to get
login information because of the double hop problem. When this occurs, you should create two
LobSystemInstance instances. The first instance should be set up to use the Secure Store Credentials,
and the second one should be set up to use PassThrough. By setting the PassThrough method and the
ShowInSearchUI property, the search crawler will use the second instance. This property should be set at
the LobSystemInstance level and not at the LobSystem level.
Item-Level Security Trimming

A very important issue in working with external data is how to get the security access control list (ACL)
information for an item. This can be done in one of two ways:
 The external system supports NTLM Access Control via Active Directory usernames and passwords.
 The external system has its own username and password scheme.
In external systems that support NTLM via security descriptors, this is a relatively easy task by using the
WindowsSecurityDescriptorField. By using this field, you are telling the crawler which crawled property
contains the security information. Because the security information can get very large, caching will be
disabled any time you set this property.
Another option is to use a method that describes how to get the security information for a particular item.
This is called the BinarySecurityDescriptorAccessor method. This method would need to return an array
of bytes with the security information that needs to be added to the index. This is used for external
systems that do not support NTLM and need to have external users mapped to domain accounts and
ACLs.
The following code example shows a simple BinarySecurityDescriptorAccessor method:
Example BinarySecurityDescriptorAccessor Method

private Byte[] GetSecurityDescriptor(string domain, string username)
{
NTAccount acc = new NTAccount(domain, username);
SecurityIdentifier sid =
(SecurityIdentifier)acc.Translate(typeof(SecurityIdentifier));
CommonSecurityDescriptor sd = new CommonSecurityDescriptor(false, false,
ControlFlags.None,
sid, null, null, null);
sd.SetDiscretionaryAclProtection(true, false);
//Grant full access to a specified user.

sd.DiscretionaryAcl.AddAccess(AccessControlType.Allow, sid,
unchecked((int)0xffffffffL), InheritanceFlags.None, PropagationFlags.None);
byte[] secDes = new Byte[sd.BinaryLength];

sd.GetBinaryForm(secDes, 0);
return secDes;
}
Once the data has been indexed and the security information included, only users that have access to the
items will see them in the search results.
Optimizing Crawl Performance

When crawling very large data sources, there are
some best practices that you can utilize to be sure
that your crawls will complete in an acceptable
amount of time. Some examples include:
 Implement the ChangedIDEnumerator and

DeletedIDEnumerator to support incremental
crawls of your content. This also increases
performance of clients that are doing offline
synchronization of external list data.
 Use the BinarySecrutiyDescriptorAcccessor

method, rather than passing the
WindowsSecurityDescription field in the
crawled properties.
 Use the StreamAccessor method when passing back stream data.
 Do not enumerate more than 100,000 items per call to the external system. You should utilize some
type of windowing or foldering scheme to balance out the items you are retrieving each time.
 Try not to use too much memory. It is easy to store items in memory for quick retrieval, but use this
approach judiciously to avoid excessive resource consumption.
Note: The SharePoint Search Crawler will expect items to be returned within two minutes. If
it does not receive any items in that period, it will cancel the crawl.
UseClientCachingForSearch Property
This property can be used to cache items during the enumeration phase, which can improve incremental
crawl speeds. You should not use this property if your items are over 30KB in size, which could lead to
cache misses and eliminate performance gains.
Demonstration: Exploring BDC Models for Search

The instructor will now demonstrate a BDC Connector to connect to external data.
Demonstration Steps
3. In a File Explorer window, browse to E:\Democode\NorthwindModel, and then double-click

NorthwindModel.sln.
4. Open the NorthwindModel\NorthwindModel.bdcm file.
5. Review the various methods defined in the file.

6. Open the ProductService.cs file, review the various methods defined in the file, and notice how
method names and parameters match.
7. Find the IdEnumerator, GetProductSecurity and GetProductFile methods in the model and in the
code.
Discussion: Custom BCS Connectors

What type of application data might you build a
BCS connector to index?
Lesson 2
Developing Custom Connectivity Components
In this lesson you will build upon your knowledge of the BDC search methods to explore specific ways to
build search connectors. You will learn the advantages and disadvantages of the different connector
types, which will help you to better understand which one will support your business requirements. You
will also learn some basic troubleshooting and debugging skills when working with search connectors.
Lesson Objectives
 Describe the various ways to build a search connector.
 Determine when to best use each type of connector.
 Create and deploy .NET Connectivity Connectors.
 Create and deploy Custom Connectors.

 Utilize common SharePoint interfaces to implement credential management.
 Implement best practices in search connectors.
BCS External Connectors

SharePoint 2013 search supports four types of BCS
indexing connectors. These include:
 Database connector. A Line of Business Data

connector that allows you to connect to SQL
Server® databases without writing any code.
You do have to create the BDC model by using
Visual Studio or SharePoint Designer.
 WCF connector. A Line of Business Data

Connector that allows you to consume data via
a WCF service. That service must have the
proper methods defined to feed the crawler
content.
 .NET BCS Connector. A custom repository connector that requires both a BDC model and a .NET
component. Both must implement the required operations.
 Custom BCS Connector. A custom repository connector similar to a .NET BCS connector but defined
by the ISystemUtility interface in the code. As an example, the Exchange Public Folder indexing
feature of SharePoint utilizes a custom BCS Connector.
Database Connector
This connector type is the more simple type of connector to utilize when working with SQL Server sources.
This simplicity is driven by the fact that the end user tool SharePoint Designer has wizard support to help
you build a model without writing any code. When working with more advanced models, you can also use
Visual Studio to make the necessary changes to support those advanced requirements with wizard-based
support. In addition to supporting SQL Server, it is also possible to make calls to other database platforms
by using basic database access providers.
WCF Connector
A second approach to connecting to external systems it to build a WCF service that wraps the entities you
want to expose. The advantage to using this type of connector is that you can build a simple contract
interface that will never change, yet be able to make changes to the underlying code without having to
deploy any assemblies or cause down time in your SharePoint farm. A drawback is that all of the items
you are interfacing with must be serializable to be passed over the wire. When working with WCF,
SharePoint Designer is the preferred tool because it has the simpler wizards to do the BDC model design.
It is possible to do this in Visual Studio, but much more tedious.
.NET Connector
When using this approach, BCS will connect to a .NET assembly for the implementation logic. This
assembly will be deployed to the SharePoint servers and BCS will execute it when a crawl is needed. The
assembly is typically created by using Visual Studio, using the Business Data Connectivity Model project
template. This template has a set of visual designers and code-management features that make creating
the connector very simple. In terms of authentication, you must implement all authentication to the
external system inside the connector. It is also possible to utilize the Secure Store to retrieve username
and password credentials and to utilize the BDC Username and Password filters. Unlike the WCF
connector, your .NET connector can take advantage of non-serializable types.
Custom BCS Connector

This is the most complex of all the connector types. This type of connector will require you to build all of
the logic necessary for navigating the target source to retrieve indexable items, determine the final URL of
the items, and then do all of the work you would do with a .NET connector (building the basic
stereotyped operations). This is all done by creating various classes that implement specific interfaces.
These classes must then be pointed to via special properties in the BDC model file.
Creating and Deploying .NET Connectivity Assembly

When creating a .NET Connectivity assembly, there
are several steps that must be completed. These
include:
1. Create the BDC model of your data. This means

defining an external content type that maps to
each entity\class definition that will be used.
The type property of the model will be
DotNetAssembly.
2. Define a class for each entity. This class will be

pointed to in the model by using the Class
property on the Entity node.
3. Define class methods that map to the stereotyped operations. This step is the same as any type of
model you would build, and the class method name and parameters should match exactly.
A .NET Connectivity Assembly contains a Class property for each entity:
Example of the Class Property

<Entity Name="Product" Namespace="NorthwindModel.NorthwindModel"
EstimatedInstanceCount="1000" Version="1.0.0.0">
<Properties>
<Property Name="Class"
Type="System.String">NorthwindModel.NorthwindModel.ProductService,
NorthwindModel</Property>
</Properties>
…
</Entity>
Deploying a .NET Connectivity Model

When you are ready to deploy your model, you can use Visual Studio to do so by using the Solution and
Feature deployment methodology, or you can choose to deploy manually. To deploy a .NET Connectivity
model manually, you must do the following:
1. Deploy the model to BCS
2. Deploy the assembly to BCS by using the Import-SPBusinessDataCatalogDotNetAssembly

Windows PowerShell cmdlet.
.NET Connectivity Assemblies must be deployed using a special cmdlet:
How to Deploy a .NET Connectivity Assembly

$url = "http://dev.contoso.com"
$assemblyPath = "C:\lab work\NorthwindModel\NorthwindModel\bin\Debug\NorthwindModel.dll"
$lobSystem = "NorthwindModel"
$serviceContext = Get-SPServiceContext $url

$lobSystem = Get-SPBusinessDataCatalogMetadataObject -ServiceContext $serviceContext -
BdcObjectType lobsystem -Name $lobSystem
Import-SPBusinessDataCatalogDotNetAssembly -LobSystem $lobSystem -Path $assemblyPath
Creating and Deploying Custom Connectors

BCS Custom Connectors are similar to the .NET
Connector in that you must still create code in .NET,
but the way you build the connector is very
different. In a .NET Connector, you simply create a
class with methods that you map to the model. In a
BCS Custom connector, you are creating interfaces
that can override the higher-level feature and the
way the connector executes. This is done via .NET
classes that implement very specific interfaces.
These interfaces include:
 ISystemUtility
 IConnectionManager
 ITypeReflector
 IAdminsitrableSystem
 ISystemPropertyValidator
When a user submits a BDC operation, the Execute method of the ISystemUtility class is called. The
biggest advantage to using a custom connector is its ability to be changed in case the backend logic must
be changed. Since a .NET connector contains the logic in the assembly, any time a change must be made,
the assembly must be recompiled and redeployed.
The following code example shows a BDC model LobSystem element that specifies a custom connector
type:
Specifying a Custom Type in a LobSystem Element

<LobSystem Name="MyFileSystem" Type="Custom">
<Properties>
<Property Name="SystemUtilityTypeName"
Type="System.String">MyFileConnector.MyFileConnector, MyFileConnector, Version=1.0.0.0,
Culture=neutral, PublicKeyToken=15865f58b9878bf8</Property>
<Property Name="InputUriProcessor"
Type="System.String">MyFileConnector.MyFileLobUri, MyFileConnector, Version=1.0.0.0,
Culture=neutral, PublicKeyToken=15865f58b9878bf8</Property>
<Property Name="OutputUriProcessor"
Type="System.String">MyFileConnector.MyFileNamingContainer, MyFileConnector,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=15865f58b9878bf8</Property>
</Properties>
…
</LobSystem>
Installation and Deployment

Both the .NET and Custom connector must have a BDC model file. This file should be deployed to the
Business Connectivity Service Application. In terms of deployment, the main difference between the .NET
connector and the custom connector is that the custom connector assemblies must be deployed to client
computers in addition to the SharePoint server if you want to support offline access. Because you must
install code on the client machines, you must also have the privileges to install the code on those
machines. When you create a .NET connector, you need only deploy the assembly to the SharePoint
server.
Major Differences
In addition to the deployment differences, there are other significant changes that one must consider.
These include:
 Ability to override the default TypeReflector implementation.

 No enforcement of a one-to-one mapping of a BDC entity and .NET class.
 You can utilize any of the security authentication methods provided by BCS in your custom
connector. This is in contrast to being forced to use PassThrough in a .NET connector.
 No tooling support via Visual Studio or SharePoint Designer for custom connectors.
Custom connectors are the recommended approach for implementing a connector for frequently
changing back-end interfaces.
Storing External System Credentials

You should always consider the method you will use
to retrieve the credentials that you will use to
connect to the external source. There are several
methods you can choose from, but only a few offer
true security. Some examples include:
 Embed the credentials in the assembly. This is a

very simple approach, but can be costly if the
credentials are changed and you need to
recompile the code.
 Place the credentials in the BDC model file. This
approach is not so simple, but offers the
flexibility to change the credentials by updating
the model file.
 Store the credentials in an external source (non-SharePoint). You could save the credentials in an
external database and retrieve them via your code. There are no real drawbacks to this approach if
everything is designed properly
 Store the credentials in SharePoint Secure Store. Since most service application and features in
SharePoint rely on this service, it may be better to utilize it in your search connector as well. This
requires you to make the call to the Secure Store and retrieve the credentials. This means that you
need to know the application id from which you want to retrieve the credentials.
If you decide to implement the Secure Store approach, you will need to specify in your code or in the BDC
model file which AppId has the credential you are looking for. The best approach is to put this AppId in
the BDC model file and then make the call to the secure store. In order to interrogate the BDC model
properties, you must implement the IContextProperty interface.
Search Connector Best Practices

No matter what type of connector you are building,
there best practices that you should follow. These
include:
 Use Identifiers. Make sure that all your entities

have a unique identifier. When working with
databases, this would map to the primary key
of the table that holds the entity data.
 Handle null values. Be sure that you are

working properly with null values. This can be
done in several ways, including translating null
values to empty strings, setting the Nullable
type to your type descriptors, or using the
NormalizeString interpretation of the BDC model.
 Match parameter names. Parameter names are case sensitive; make sure that your BDC model and
.NET assembly method signatures match.
 Handle exceptions. In most cases (update operations are okay) it is not appropriate for an exception to
be passed to BDC. If something does not work, simply return a null value.
Troubleshooting and Debugging BCS Connectors

There are several common errors that you will come
across when attempting to execute crawls by using
a search connector. These include:
 Can’t select BDC Model in Search Content

Source. You didn’t add the ShowInSearchUI
property, the RootFinder property, or
implement the IDEnumerator required
stereotyped methods.
 Access Denied by Business Data Connectivity.

This error occurs when you haven’t specified
permissions in the data model. When you
attempt to access the data via the model, the
account that is executing the read methods will need to have at least Execute permissions. This can be
the default access account, a crawl rule account, or the search service application pool identity.
 Crawl log shows two success messages and no errors. You didn’t specify a RootFinder in your BDC
model.
 The model does not show up as available in the New Content Source page. You didn’t specify the
ShowInSearchUI property in your model.
 An error displays about the database response being throttled. A typical BDC model will limit the
number of items to be returned before it will error. This is configured at the proxy level by using
Windows PowerShell.
 Item ID is indexed, but no metadata is displayed. You have placed the UseClientCachingForSearch on
the IdEnumerator and Finder methods.
 Error message doesn’t change even though you updated the model and code. Make sure that you
change the version number on the entity so that SharePoint knows something changed. You may
need to restart the Search Service to be certain that the old version is replaced correctly with the new
version.
 Cannot see fields in the update and insert forms. Confirm that you have placed the UpdaterField and
CreaterField attributes on each TypeDescriptior that you want to display.
 You get an identifier error when you attempt to update an item. Set all return identifiers to
ReadOnly=”true”.
The following code example shows how to disable throttling for BDC queries:
Disabling Throttling for BDC Queries

$proxy=Get-SPServiceApplicationProxy |
where {$_.TypeName -match "Business Data Connectivity Service Application Proxy"}
#"Business Data Connectivity Proxy"}
$throttleItems=Get-SPBusinessDataCatalogThrottleConfig -Scope DataBase -ThrottleType
Items -ServiceApplicationProxy $proxy
Set-SPBusinessDataCatalogThrottleConfig –Enforced:$false -Identity $throttleItems
$throttleItems=Get-SPBusinessDataCatalogThrottleConfig -Scope DataBase -ThrottleType
Items -ServiceApplicationProxy $proxy
$throttleItems
$throttleconnections=Get-SPBusinessDataCatalogThrottleConfig -Scope Global -ThrottleType
Connections -ServiceApplicationProxy $proxy
Set-SPBusinessDataCatalogThrottleConfig –Enforced:$false -Identity $throttleconnections
$throttleconnections=Get-SPBusinessDataCatalogThrottleConfig -Scope Global -ThrottleType
Connections -ServiceApplicationProxy $proxy
$throttleconnections
iisreset
These errors will display in the Crawl log in the Search Service Application. These are high-level errors, and
if you want to learn more about what has occurred you can utilize the ULS logs to find the BDC error. It is
best if you set the log level to Verbose to get all the stack trace log data.
Utilize the ULSView.exe tool to sort based on the mssdmn.exe process in real time. This can help you
diagnose what may be occurring in your connector. You can also connect to this process by using Visual
Studio to debug and step through your connector code.
Lesson 3
Working with External Events and Notifications
In the lesson you will learn to enable external lists to support event receivers. This process involves adding
special stereotyped operations to support subscriptions in SharePoint and in the external system. This also
means you must learn the basic elements needed to support subscriptions in the external system. This
lesson will provide you with the knowledge you need to design, implement, and troubleshoot these new
features in SharePoint 2013.
Lesson Objectives
 Describe the difference between alerts and external events.
 Configure external notifications.
 Configure support for external events.

 Describe how to implement the Subscribe and Unsubscribe methods.
 Describe how to initiate subscriptions.
 Format event notification messages.
 Configure event receivers on external lists.
Event and Notification Features

SharePoint 2013 BCS has been improved to provide
event-based features to external lists. For example,
you can now create alerts on external lists. This is
made possible by the combination of new
stereotyped BDC model methods that make calls
out to external systems to initiate subscriptions.
 Alerts. These allow uses to receive email
notification when items are added, modified, or
deleted in a list. In 2010, this was not possible
with external lists, but is now available by using
remote event receivers
 Event receivers. Because SharePoint can now

receive notifications of changes in the external system, you can now use Event receivers on your
external lists.
 Remote Event Receivers. These allow SharePoint to make a call out to external sources when an event
occurs on a list in SharePoint.
Enabling External System Events

BCS provides all the internal plumbing needed to
work with external events. However, it is not always
the case that the external system will support
sending events to potential subscribers. In order for
the external system to support all the necessary
components in BCS, you must do the following:
 Create a subscription persistent store.
 Create a changes persistent store.
 Create a Polling\Notification Service.
Subscription Persistent Store

When a user wants to create a subscription to an external event, they will be given some mechanisms to
do this, which will in turn cause a request to subscribe to be sent to the external system. This means that
the external system must have an endpoint available to accept that request. The request will be sent in
ATOM or XML form and will include the subscription information, including the delivery address URL in
the body or optionally in the querystring of the request. When this subscription request is received, your
subscription persistent store must save the information so it knows where it needs to send the change
events.
Changes Persistent Store

When changes are made to the system, you have two options. Send the notifications asynchronously
when the change is made, or record that the change has occurred and send the notification later. If you
choose the latter, you will need to save those changes into some persistent store where a polling service
can pick up the change and send the necessary details to SharePoint via the delivery address.
Polling\Notification Service
If you choose not to send the notifications in real time, you can have a polling service monitor for changes
in the external source and then have it send the changes to SharePoint. This can be done in any number
of ways, but the most common way is a Windows service.
BCS Events Feature

In addition to creating an external system that
supports received subscription requests, you must
enable a feature on each SharePoint web that will
create a special subscription list. This list has several
columns that keep track of the subscriptions set up
by the users:
 LobSubscriptionId
 EntityName
 EntityNamespace
 LsiName
 ForwarderType
 CallbackUrl
 NotificationContext
 EntityEventType
In order to activate the feature, you can activate the hidden BCSEvents feature via Windows PowerShell,
server-side object model, or the client-side object model. When activating this feature, it will make a call
to a feature event receiver that in turn activates the ExternalSubscriptions feature, which is not hidden and
will display in the SharePoint site’s settings page.
In order to create subscriptions and external event notification, you must create a hidden subscription list
via a feature:
Enabling the BCSEvents Feature via CSOM

function EnableEventing_Clicked() {
var clientContext = SP.ClientContext.get_current();
var web = clientContext.get_web();
var features = web.get_features();
clientContext.load(features);
var eventingFeatureId = new SP.Guid('5B10D113-2D0D-43BD-A2FD-F8BC879F5ABD');

var eventingFeature = features.add(eventingFeatureId, true,
SP.FeatureDefinitionScope.farm);
clientContext.load(eventingFeature);
var onEventingFeatureActivated = function () {
alert("eventing feature activated");
};
clientContext.executeQueryAsync(Function.createDelegate(this,
onEventingFeatureActivated));
}
Once this list has been created, any calls to the Subscribe and Unsubscribe methods of the BDC model
will record the subscription in this hidden list.
Implementing BDC Event Methods

The set of BDC method types have been extended
to include two methods that support external event
subscriptions. These include the Subscribe and
Unsubscribe method types.
BDC Model Attributes

These BDC model methods contain special
attributes that are used to designate the return
parameters. These include:
 IsDeliveryAddress. This tells the method to
place the delivery address in the specified
property.
 IsEventType. This tells the method to place the event type in the specified property.
 IsOnBehalfOfField. This field will pass in the user data that requested the subscription.
 SubscriptionIdName. This represents the subscription id of the current request.
When implementing these methods, the choice of your BDC model data is important. When utilizing
OData feeds, the set of properties you will use will be considerably different than if you were simply
connected to a simple database. You can see examples of the differences between the two in the
following code snippets. What you will see is that the database model is considerably easier to utilize,
since it is using only stored procedures. When working with the OData model, you must implement
several extra different properties, including:
 ODataEntityUrl. The target URL directory (the prefix of the URL is taken from the LobSystemInstance)
of where the request should be sent. This will change based on if you are doing a POST or a GET
 ODataHttpMethod. The HTTP method (POST, GET, DELETE, and so forth).
 ODataPayloadKind. The type of ATOM body that should be sent; this is typically set to Entry or
Parameter.
 ODataFormat. This is the Content-Type header that gets sent to your OData service.
 ODataServiceOperation. A boolean to indicate if the endpoint is a basic WCF service operation or not.
In each example, you will see that a set of parameters is passed to the target, with the two most important
being the DeliveryAddress and the EventType. The DeliveryAddress is the SharePoint endpoint that will
contain a subscription ID that is recorded in a hidden list in the SharePoint site. When a post is received to
this endpoint, the subscription ID must exist in the list, or you will receive an HTTP 404 error. The event
type is used to designate if the event is an addition, modification, or a deletion. The enumerations are as
follows:
 Addition = 1
 Modification = 2
 Deletion = 3
As a return parameter to the two different examples below, you will notice that you must pass back the
external systems subscription ID. This is later used for when a user wishes to remove an alert or the system
removes an event handler. When one of these actions occurs, SharePoint must send a request to the
external system with the subscription ID that the external system should delete.
The following code example illustrates the Subscribe and Unsubscribe methods for a database model:
Subscribe and Unsubscribe Methods in a Database Model

<Method IsStatic="false" Name="Subscribe">
<Properties>
<Property Name="BackEndObject"
Type="System.String">Subscriptions</Property>
<Property Name="BackEndObjectType"
Type="System.String">SqlServerTable</Property>
<Property Name="RdbCommandText" Type="System.String">IF NOT EXISTS
(SELECT [SubscriptionId] FROM [Subscriptions] WHERE [DeliveryAddress] = @deliveryAddress)
BEGIN INSERT INTO [Subscriptions]([DeliveryAddress] , [EventType])
VALUES(@deliveryAddress , @eventType) END SELECT TOP 1 [SubscriptionId] FROM
[Subscriptions] WHERE [DeliveryAddress] = @deliveryAddress</Property>
<Property Name="RdbCommandType" Type="System.Data.CommandType,
System.Data, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089">Text</Property>
<Property Name="Schema" Type="System.String">MiniCRM</Property>
</Properties>
<Parameters>
<Parameter Direction="In" Name="deliveryAddress">
<TypeDescriptor TypeName="System.String" Name="deliveryAddress">
<Properties>
<Property Name="IsDeliveryAddress"
Type="System.Boolean">true</Property>
</Properties>
</TypeDescriptor>
</Parameter>
<Parameter Direction="In" Name="eventType">
<TypeDescriptor TypeName="System.String" Name="eventType">

<Properties>
<Property Name="IsEventType" Type="System.Boolean">true</Property>
</Properties>
</TypeDescriptor>
</Parameter>
<Parameter Direction="Return" Name="Subscribe">
<TypeDescriptor TypeName="System.Data.IDataReader, System.Data,
Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" IsCollection="true"
Name="Create">
<TypeDescriptors>
<TypeDescriptor TypeName="System.Data.IDataRecord, System.Data,
Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" Name="CreateElement">
<TypeDescriptors>
<TypeDescriptor TypeName="System.Int32" ReadOnly="true"
Name="SubscriptionId">
<Properties>
<Property Name="SubscriptionIdName"
Type="System.String">SubscriptionId</Property>
</Properties>
<Interpretation>
<ConvertType LOBType="System.Int32" BDCType="System.String"
/>
</Interpretation>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</TypeDescriptors>
</TypeDescriptor>
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Type="EventSubscriber" ReturnParameterName="Subscribe"
Default="true" Name="Subscribe" DefaultDisplayName="Read Item WcfCustomer">
<Properties>
</Properties>
</MethodInstance>
</MethodInstances>
</Method>
<Method IsStatic="false" Name="Unsubscribe">
<Properties>
<Property Name="BackEndObject"
Type="System.String">Subscriptions</Property>
<Property Name="BackEndObjectType"
Type="System.String">SqlServerTable</Property>
<Property Name="RdbCommandText" Type="System.String">DELETE FROM
[Subscriptions] WHERE [SubscriptionId] = @SubscriptionId</Property>
<Property Name="RdbCommandType" Type="System.Data.CommandType,
System.Data, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089">Text</Property>
<Property Name="Schema" Type="System.String">MiniCRM</Property>
</Properties>
<Parameters>
<Parameter Direction="In" Name="SubscriptionId">
<TypeDescriptor TypeName="System.Int32" Name="SubscriptionId">
<Properties>
</Properties>
<Interpretation>
<ConvertType LOBType="System.Int32" BDCType="System.String" />
</Interpretation>
</TypeDescriptor>
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Type="EventUnsubscriber" Name="Unsubscribe"
DefaultDisplayName="UnSubscriber">
<Properties>
</Properties>
</MethodInstance>
</MethodInstances>
</Method>
The following code example illustrates the Subscribe and Unsubscribe methods for an OData model:
Subscribe and Unsubscribe Methods in an OData Model

<Method Name="SubscribeCustomer" DefaultDisplayName="Customer Subscribe" IsStatic="true">
<Properties>

<Property Name="ODataEntityUrl"
Type="System.String">/Subscribe?DeliveryURL='@DeliveryURL'&EventType=@EventType&E
ntityName='@EntityName'&SelectColumns='@SelectColumns'</Property>
<Property Name="ODataHttpMethod" Type="System.String">GET</Property>
<Property Name="ODataPayloadKind"
Type="System.String">Property</Property>
<Property Name="ODataFormat"
Type="System.String">application/json;odata=verbose</Property>
<Property Name="ODataServiceOperation"
Type="System.Boolean">false</Property>
</Properties>
<AccessControlList>
<AccessControlEntry Principal="NT Authority\Authenticated Users">
<Parameters>
<Parameter Direction="In" Name="@DeliveryURL">
<TypeDescriptor TypeName="System.String" Name="DeliveryURL" >
<Properties>
<Property Name="IsDeliveryAddress"
Type="System.Boolean">true</Property>
</Properties>
</TypeDescriptor>
</Parameter>
<Parameter Direction="In" Name="@EventType">
<TypeDescriptor TypeName="System.Int32" Name="EventType" >
<Properties>
<Property Name="IsEventType" Type="System.Boolean">true</Property>
</Properties>
</TypeDescriptor>
</Parameter>
<Parameter Direction="In" Name="@EntityName">
<TypeDescriptor TypeName="System.String" Name="EntityName" >
<DefaultValues>
<DefaultValue MethodInstanceName="SubscribeCustomer"
Type="System.String">Customers</DefaultValue>
</DefaultValues>
</TypeDescriptor>
</Parameter>
<Parameter Direction="In" Name="@SelectColumns">
<TypeDescriptor TypeName="System.String" Name="SelectColumns" >
<DefaultValues>
<DefaultValue MethodInstanceName="SubscribeCustomer"
Type="System.String">*</DefaultValue>
</DefaultValues>
</TypeDescriptor>
</Parameter>
<Parameter Direction="Return" Name="SubscribeReturn">
<TypeDescriptor Name="SubscriptionId" TypeName="System.String" >
<Properties>
</Properties>
</TypeDescriptor>
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Type="EventSubscriber"
ReturnParameterName="SubscribeReturn" ReturnTypeDescriptorPath="SubscriptionId"
Default="true" Name="SubscribeCustomer" DefaultDisplayName="Customer Subscribe">
<AccessControlList>
</MethodInstance>
</MethodInstances>
</Method>
<Method Name="UnSubscribeCustomer" DefaultDisplayName="Customer Unsubscribe">
<Properties>
<Property Name="ODataEntityUrl"
Type="System.String">/UnSubscribe?ID='@ID'</Property>
<Property Name="ODataHttpMethod" Type="System.String">GET</Property>
<Property Name="ODataPayloadKind"
Type="System.String">Property</Property>
<Property Name="ODataServiceOperation"
Type="System.Boolean">false</Property>
</Properties>
<AccessControlList>
<Parameters>
<Parameter Name="@ID" Direction="In">
<TypeDescriptor Name="ID" TypeName="System.Int32">
<Properties>
Type="System.String">ID</Property>
</Properties>
<Interpretation>
<ConvertType LOBType="System.Int32" BDCType="System.String" />
</Interpretation>
</TypeDescriptor>
</Parameter>
</Parameters>
<MethodInstances>
<MethodInstance Name="UnSubscribeExpenseReport"
DefaultDisplayName="ExpenseReport
Unsubscribe" Type="EventUnsubscriber" Default="true">
<AccessControlList>

</MethodInstance>
</MethodInstances>
</Method>
Notification Parsers
When the external system needs to report information about a change back to SharePoint, the format
must be very specific. There are two out-of-the-box formats that you can implement. They are:
 IdentityParser. Accepts an Atom message with a set of identities in the message body.
 ODataEntryContentNotificationParser. Accepts a message with all the attributes of an item.
 Custom. A notification parser that you build that must inherit from NotificationParser class.
If you do not specify a content parser in your BDC method signature then the default will be
IdentityParser. If you want to customize the message format then you can also implement a custom
parser using the NotificationParser abstract class. To specify which parser you want to implement you
add the NotificationParserType entry to the model method.
The following code example shows a NotificationParserType entry:
Defining the NotificationParserType

<Property Name="NotificationParserType" Type="System.String">
ODataEntryContentNotificationParser
</Property>
When using the Identity parser, you must have a message that has a valid XPath to the identity values.
The valid XPath is /a:feed/a:entry/a:content/m:properties/b:BcsItemIdentity. When using the
ODataEntryContentNotificationParser, the valid XPath is /a:entry/a:link/m:inline/a:entry.
When using the default Identity parser, you should send a response formatted with a simple set of
identities passed in the xml:
An Example of Identity Notification Format

format = @"<?xml version=""1.0"" encoding=""utf-8"" standalone=""yes""?>
<feed xml:base=""http://services.odata.org/OData/OData.svc/""
xmlns:d=""http://schemas.microsoft.com/ado/2007/08/dataservices""
xmlns:m=""http://schemas.microsoft.com/ado/2007/08/dataservices/metadata""
xmlns:b=""http://schemas.microsoft.com/bcs/2012/""
xmlns=""http://www.w3.org/2005/Atom"">
<entry>
<title type=""text"">Customers</title>
<id>http://www.northwind.com/customers</id>
<author>
<name>External System</name>
</author>
<content type=""application/xml"">
<m:properties>
<b:BcsItemIdentity m:type=""Edm.String""><CustomerID>{0}</CustomerID></b:BcsItemIdentity>
<d:Name>Customer</d:Name>
</m:properties>
</content>
</entry>
</feed>
";
Initiating Subscriptions
Once you have set up both SharePoint and the
external system to support notification events, users
can create subscriptions. A subscription can be
created by clicking a button that has custom code,
creating an alert, some kind of code that adds an
event handler to an external list, or a workflow that
wants to listen for events on an external list. The
entire flow of the subscription process is:
1. User submits a subscription request for

notification.
2. SharePoint generates a delivery address.
3. Subscription request is sent to the external LOB system.

4. LOB application receives the request.
5. LOB generates a local subscription ID.
6. LOB saves the subscription and sends back the subscription ID to SharePoint.
7. SharePoint saves the subscription ID in the hidden Subscription list.
The flow of the notification process is:
1. A change occurs in the LOB.
2. LOB monitoring application picks up the change and creates a message.
3. LOB monitoring application sends the message to the delivery address.
4. SharePoint receives the request.

5. SharePoint executes the event receivers.
The flow of the unsubscribe is similar to the subscription process:
1. User submits a unsubscribe request.

2. SharePoint formats a message with the subscription ID and sends to LOB.
3. LOB receives the request.
4. LOB removes the subscription from its local store.

In order to create a subscription, you can use any of the SharePoint API interfaces. The subscription is
created by calling the Subscribe method of the entity. This method takes the event type and the
notification callback as parameters. You can also optionally specify a user, the BCD instance method, and
the LOB system instance as parameters. As previously mentioned, you don’t need to explicitly call the
subscribe method to create a subscription; this is automatically called when you perform various actions
via the SharePoint UI, such as creating an alert.
Note: A common mistake when doing development with subscriptions is that you may not
see the Alerts button in the ribbon on an external list. This is because you have not set up
outgoing email at the Farm level, and therefore the alert button will not display on any lists.
Subscriptions must be created (explicitly or implicitly) in order to receive external notification events:
JSOM Example of Creating a Subscription

function SubscribeEntity() {
var notificationCallback = new SP.BusinessData.Runtime.NotificationCallback(context,
"http://localhost:19739/northwind.svc");
var url = web.get_url();
notificationCallback.set_notificationContext(url);
context.load(notificationCallback);
var subscription = entity.subscribe(1, notificationCallback,
"administrator@contoso.com", "SubscribeCustomer", lobSystemInstance);
context.load(subscription);
context.executeQueryAsync(OnSubscribeSuccess, failmethod);
}
You should be aware that you can have multiple subscriptions for the same event, yet for different
individuals. You should plan accordingly to be sure that your external system can support sending several
hundreds or thousands of notifications within small windows.
External List Event Receivers

Event Receivers are SharePoint server-side events
that are executed when something happens on a
SharePoint object. These objects include sites, webs,
lists, and list items. For the purpose of this module,
we are interested in the SPItemEventReceiver,
which is executed on a list item. These list item-level
events include events such as adding, moving,
deleting, checking in, and checking out an item.
When those events occur, your code, and
SharePoint code, can be executed.
Up until SharePoint 2013, external lists could not

have an event receiver on them because SharePoint
had no way of knowing when these events occurred. SharePoint could only know about the events that
occur on data it maintained. With the introduction of the new notifications architecture, event receivers
can now be placed on external lists. When adding a new event receiver, the process is no different than if
you were adding to a SharePoint hosted list.
Because the architecture of the notification feature is abstracted from the main SharePoint UIs, all features
will work, including alerts and workflows. The biggest difference is the ExternalNotificationMessage
property of the SPItemEventProperties class. This message is of type ReadOnlyCollection<byte>, and
any data received from the external event will be present in this property. This is a UTF8 encoding string
that can be converted back to the message by passing in the property as a byte array to the
Encoding.UTF8.GetString method.
Remote Event Receivers

In addition to local event receivers, you can also apply remote event receivers that will make a call to an
external endpoint that lives outside of SharePoint. This is similar to but different from the Subscriber and
Unsubscriber methods presented earlier, and can be used across any SharePoint list. Rather than
executing code local to SharePoint, you can now make calls to external systems to notify them of events
that have occurred on SharePoint lists (both internal and external lists).
Note: When creating an event receiver, you must create an assembly and deploy it to the
GAC of each server in the SharePoint farm. This is best done with a SharePoint Farm solution.
The following code example illustrates how to add an event receiver to an external list:
Adding an Event Receiver to an External List

public class EntryContentEventReceiver : SPItemEventReceiver
{
public override void ItemAdded(SPItemEventProperties properties)
{
base.ItemAdded(properties);
string msg =
Encoding.UTF8.GetString(properties.ExternalNotificationMessage.ToArray());
}
}
Demonstration: Working with External Events

In this demonstration, your instructor will demonstrate how to deploy an OData BCS model that support
event subscriptions.
Demonstration Steps
Note: These instructions include all of the steps required to complete the demonstration.
The instructor may complete some of these steps before the students begin the demonstration.
2. Log on to the LONDON machine as CONTOSO\Administrator with the password Pa$$w0rd.
4. In File Explorer, browse to E:\Democode\NorthwindService, and then double-click

NorthwindService.sln.
5. In Solution Explorer, notice that the solution has five projects. The ExternalListEventReceiver project
is an event receiver that will interrogate an external message and should be placed on an external list.
The NorthwindApp project is a SharePoint App that deploys a BDC OData Model and has a default
page that has a button to subscribe to events and enable the required features. The
NorthwindService project is the OData project that exposes the back-end database as an OData
feed. It has also been extended to have subscription methods. The NotificationTesting project
allows you to send a response to the SharePoint endpoint for event testing. The PollingService
project is a Windows service that will poll for changes in the database and then send events to
SharePoint based on those changes.
6. Right-click ExternalListEventReceiver, and then click Deploy.
7. Right-click NorthwindService, point to Debug, and then click Start new instance.
Explain that this deploys the OData service used by the BDC model.
Administration.

10. Click Business Data Connectivity Service.
11. On the ribbon, click Import.
12. On the Import BDC Model page, click Browse.
13. In the Choose File to Upload dialog box, browse to

E:\Democode\NorthwindService\NorthwindApp\External Content Types\Northwind, click
Customers.ect, and then click Open.
14. On the Import BDC Model page, click Import.
15. On the BDC Model was successfully imported page, click OK.
16. Select the NorthwindModel check box.
17. On the ribbon, in the Permissions section, click Set Object Permissions.
18. In the Set Object Permissions dialog box, in the People Picker box, type administrator, and then
click Add.
19. Under Permissions for CONTOSO\administrator, select all the check boxes, and then click OK.
20. Click NorthwindModel.

21. Select the Customers check box.
22. On the ribbon, in the Permissions section, click Set Object Permissions.
23. In the Set Object Permissions dialog box, in the People Picker box, type administrator, and then
click Add.
24. Under Permissions for CONTOSO\administrator, select all the check boxes, and then click OK.
25. Open a new browser tab. In the address bar, type http://team.contoso.com, and then press Enter.
26. On the Contoso Team Site page, click Site Contents.
27. On the Site Contents page, click add an app.
28. On the Your Apps page, click External List.
29. In the Adding External List dialog box, in the Name box, type Customer.
30. In the External Content Type box, click Select External Content Type.
31. In the External Content Type Picker dialog box, click Northwind, and then click OK.
32. In the Adding External List dialog box, click Create.
33. On the Site Contents page, click the Customer link. It should display data from the OData feed,
which is in turn coming from the database.
34. Switch to Visual Studio.
35. In Solution Explorer, expand Northwind.svc, and then double-click Northwind.svc.cs.
36. Right-click the first line of the Subscribe method, point to Breakpoint, and then click Insert
Breakpoint.
37. On the Windows Start page, type SQL, and then click SQL Server Management Studio.
39. In Object Explorer, expand Databases, expand Northwind, and then expand Tables.
40. Right-click dbo.EntitySubscribe, click Select Top 1000 Rows. Notice that there are no rows in the
table.
41. On the Windows Start page, type SharePoint, right-click SharePoint 2013 Management Shell, and
then click Run as administrator.
42. At the command prompt, type E:\Democode\SetupeventReceiver.ps1, and then press Enter.
Monitor Visual Studio for the breakpoint to be hit. Highlight the method variables to see that the
values were sent from SharePoint.
43. In Visual Studio, press F5 to continue.
44. Switch back to SQL Server Management Studio, click Execute to refresh the table rows. You should
now see one row. Notice the DeliveryURL address.
45. Switch back to Visual Studio, in the NotificationTesting project, double-click Program.cs. Notice
how it simply gets the latest delivery address and then sends an http post to that address. Notice also
that the message that is sent is an Atom Feed.
46. On the DEBUG menu, click Attach to Process.
47. In the Attach to Process dialog box, select the Show processes from all users check box.
48. Select all the w3wp.exe processes, and then click Attach.
49. In the Attach Security Warning dialog box, click Attach.
53. On the DEBUG menu, click Attach to Process.
54. In the Attach to Process dialog box, click the OWSTIMER.exe process, and then click Attach.
56. In Solution Explorer, under ExternalListEventReceiver, double-click BCSEventReceiver.cs.
57. Right-click the following line of code, point to Breakpoint, and then click Insert Breakpoint:
base.ItemAdded(properties);
58. In Solution Explorer, right-click NotificationTesting, point to Debug, and then click Start new
instance. When the break point gets hit in your event receiver, SharePoint has successfully received
the message.
59. Press F5 to continue.
60. Switch to SharePoint Central Administration.
61. Click Central Administration.
64. On the ribbon, in the View section, in the list, click BDC Models.
65. Select the NorthwindModel check box.
66. On the ribbon, click Delete.

69. In Visual studio, on the DEBUG menu, click Stop Debugging.

72. Close SharePoint 2013 Management Shell.

Lab: Creating and Deploying a .NET Connectivity

Assembly
Scenario
Contoso has a subsidiary company called Northwind that would like to use the Contoso SharePoint Farm
to index their product data. They have asked you as the Contoso Senior SharePoint Developer to help
them architect and build a solution. The basic requirements are that the users would like to be able to
search on product data from multiple data sources using SharePoint Search and be able to update that
data using SharePoint interfaces. The product data is spread across two separate databases. They have
asked you to present all the data in the two databases as a single item in the search results and in an
external list. You have been tasked with using BCS Search Connector framework to accomplish this
business requirement.
Objectives
 Create a .NET Connectivity Assembly.
 Implement entity stereotyped methods.
 Implement .NET methods to support the connector model.
 Deploy and test .NET Connectivity Assemblies.
 Set up search to use the .NET Connector for indexing.
Lab Setup

Exercise 1: Create a .NET Connectivity Assembly

Scenario
In this exercise you will create a new SharePoint project by using Visual Studio, and add and configure a
BDC model that supports .NET Connectivity classes.
1. Use Visual Studio to Create New BDC Model
2. Define Entity Properties
3. Define Entity Methods

4. Implement Entity Methods
5. Set Up Secure Store Authentication
6. Configure the Model for Search

 Task 1: Use Visual Studio to Create New BDC Model

password Pa$$w0rd.
3. In Visual Studio create a new project named NorthwindModel. You should use the following
properties to create the project:
Property Value
Template SharePoint – Empty Project
Location E:\Labfiles\Starter
Solution type Farm solution
Development site http://dev.contoso.com
4. Add a new BDC model called NorthwindModel to the project.
 Task 2: Define Entity Properties

1. Modify the model to contain a single entity named Product with an Int32 identifier named
ProductId.
2. In the Product entity class, add the following code to define the properties:
// Properties in first database

public int ProductId { get; set; }
public string Name { get; set; }
public string Description { get; set; }
public string RetailPrice { get; set; }
public string QuantityPerUnit { get; set; }
// Properties in second database
public string ProductManager { get; set; }
public string Manufacturer { get; set; }
public string CostBasis { get; set; }
 Task 3: Define Entity Methods

1. Complete the implementation of the ReadItem method based on the properties of the Product
class.
2. Complete the implementation of the ReadList method based on the properties of the Product class.
3. In the Methods element, before the closing tag, press Enter.
4. On the EDIT menu, click Insert File As Text.
5. In the Insert File dialog box, browse to E:\Labfiles\Starter, and in the file extension list, click Text
Files (*.txt).
6. Click MethodDefinitions.txt, and then click Open
7. Review the method definitions you have just added to the model.
8. Save your work.
 Task 4: Implement Entity Methods

1. Add references to the following assemblies:
o C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.Office.SecureStoreService\v4.0_15.0.0.
0__71e9bce111e9429c\Microsoft.Office.SecureStoreService.dll.
o C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.Office.SecureStoreService.Server.Securi
ty\v4.0_15.0.0.0__71e9bce111e9429c\Microsoft.Office.SecureStoreService.Server.Security.dll.
o C:\Program Files\Common Files\Microsoft Shared\Web Server

Extensions\15\ISAPI\Microsoft.BusinessData.dll.
o System.Web.
2. Add using statements for the following namespaces (you can find a copy of these using statements in
the E:\Labfiles\Starter\UsingStatements.txt file):
o System.Data
o System.Data.SqlClient
o System.IO
o System.Runtime.InteropServices
o System.Security
o System.Security.AccessControl
o System.Security.Principal
o Microsoft.Office.SecureStoreService.Server
o Microsoft.BusinessData.Infrastructure.SecureStore
o Microsoft.BusinessData.Infrastructure.SecureStore
o Microsoft.BusinessData.SystemSpecific
o Microsoft.BusinessData.Runtime
o Microsoft.BusinessData.MetadataModel
o Microsoft.BusinessData.MetadataModel.Collections
3. Delete the existing ReadItem method.
4. Delete the existing ReadList method.

5. In the ProductServices.cs, file, at the end of the ProductService class, before the closing brace, press
Enter.

Files (*.txt).
8. Click EntityMethods.txt, and then click Open.
9. Review the code you have just added to the code file.
10. Save your work.
 Task 5: Set Up Secure Store Authentication

1. Modify the class definition to implement the IContextProperty interface.
2. Declare a public static variable named username of type string. Initialize the variable to an empty
string.
3. Declare a public static variable named password of type string. Initialize the variable to an empty
string.
4. Add properties to the class to implement the IContextProperty interface. You should implement the
properties by automatic properties.
5. In the ProductService class, after the last of the property declarations, press Enter.
Files (*.txt).
8. Click SecureStoreCode.txt, and then click Open.
9. Review the code that you have just added.
10. Use the Central Administration web site to create a new Secure Store Application called Northwind
with the following properties:
Property Value
Display Name Northwind
Contact E-mail administrator@contoso.com
Target application type Group
Field Name (user name) User Name
Field Name (password) Password
Field Type (user name) User Name
Field Type (password) Password
Application administrator CONTOSO\Administrator
Applications members CONTOSO\Domain Users
11. Set the credentials for the Northwind application to use the username sqluser, and the password
Pa$$w0rd.
12. In Visual Studio in the NorthwindModel.bdcm file, in the LobSystemInstances element, add a
LobSystemInstance element with a Name attribute with the value NorthwindModel.
13. Add a child Properties element.

14. Add a child Property element with the value Northwind, and the following attributes:
Attribute Value
Name AppId
Type System.String
15. Save your work.
 Task 6: Configure the Model for Search

1. Add a new property to the NorthwindModel LobSystem, with the name ShowInSearchUI, and the
value x.
2. Add a new property to the ReadItem Method, with the name RootFinder, and the value Empty.
Results: A .NET connectivity search connector model.
Exercise 2: Deploying and Testing a .NET Connectivity Model

Scenario
You have successfully built a .NET Connectivity model, and now you must deploy the search connector
and test it by using the BDC web parts and search interfaces.
1. Deploy the .NET Connectivity Solution
2. Test the .NET Connectivity Solution by Using a BCS Web Part
3. Test the .NET Connectivity Solution by Using an External List
4. Set Up BDC Search
 Task 1: Deploy the .NET Connectivity Solution

1. In Visual Studio, add a new property to the Feature1 feature, with the key SiteUrl, and the value
http://team.contoso.com.
2. Configure Visual Studio to always force installation of the Feature1 Feature when the solution is
deployed.
3. Use Visual Studio to deploy the BDC Model.
4. Use the Central Administration web site to verify that the NorthwindModel Feature1 farm-scoped
Feature is active.
5. Use Windows PowerShell to deploy the search connector assembly. You can find the commands in
the E:\Labfiles\Starter\DeploySearchConnector.ps1 file.
6. Use the Central Administration web site to grant permissions on the Product external content type.
You should grant the CONTOSO\Domain Users security group the Edit, Execute, Selectable in
Clients, and Set Permissions permissions. You should propagate permissions to all methods of the
content type.
Note: If you discover an error after deploying the search connector, you must retract the
solution by using Visual Studio, and then restart IIS before you can re-deploy the solution. If you
do not restart IIS after the retraction, SharePoint will use the previous version of the assembly and
you will get unexpected results.
 Task 2: Test the .NET Connectivity Solution by Using a BCS Web Part
1. Browse to the team site located at http://team.contoso.com.
2. Add a new page to the team site named Product.
3. On the new page, add a Business Data List web part to the page.
4. Configure the Business Data List web part to use the NorthwindModel.NorthwindModel.Product
external content type.
5. Save the page.
 Task 3: Test the .NET Connectivity Solution by Using an External List

1. Add an external list to the site with the following properties:
Property Value
Name Product
External content type NorthwindModel.NorthwindModel.Product
2. Browse to the Product list.
3. Add a new item to the list with the following properties:
Property Value
Name Test
Description Test description
RetailPrice 26.50
QuantityPerUnit 12
ProductManager Leave blank
Manufacturer Contoso
CostsBasis Leave blank
4. Verify that the new product has been added to the list (you will need to use the paging controls, as
the item will have been added to the end of the list).
 Task 4: Set Up BDC Search

1. Use the Central Administration web site to set the profile page host for the Product external content
type to http://team.contoso.com.
2. Create a new search content source named Northwind. Configure the content source to crawl the
NorthwindModel external data source.
3. Start a full crawl of the Northwind content source. Wait for the crawl to complete before you
continue.
4. View the crawl log for the Northwind content source. The log should indicate that more than 80
items have been crawled. Many items will have returned a warning, and some items might have
returned an error. You should not have more than five errors, but you may have a lot of warnings.
5. Browse to the search center site at http://search.contoso.com.
6. Perform a search for Chef. You should get two results.
Results: A successfully deployed .NET Connectivity model.
Question: What is the most important thing to double check when building your entity
model methods and your entity class methods?
Question: What is the reason for having multiple methods that retrieve information about
single items such as metadata, security, and file contents?

In this module you were given information about how to build BDC models that enable you to crawl and
index content in external systems. You learned various ways to build these models and what was needed
to support search functionality in SharePoint. You also learned the new stereotyped methods for
implementing a subscription and notification architecture between SharePoint and your external systems.
You now have the skills to:
 Describe BCS Connector Framework scenarios.

 Design and Develop BCS Connector stereotyped operations.
 Design and Configure BDC model security.
 Optimize Search Connector crawl performance.
 Use Visual Studio to build BDC Models for Search.
 Deploy BDC Search connectors.
 Debug and troubleshoot your search connectors.
 Design and deploy BDC event subscriber methods.
 Configure alerts and event receivers on external lists.
Review Question(s)
Test Your Knowledge
Question
Which stereotyped method is used to get a single item’s metadata?
IdEnumerator
EventSubscriber
Finder
SpecificFinder
StreamAccessor
Test Your Knowledge

Question
Which of the following is not a type of search connector model?
.NET Connector
Custom Connector
WCF Connector
COM Connector
Database Connector
Statement Answer
True or False: ShowInSearchUI is the only

property that you need to specify in a
connector model in order to use the model in
search dialogs.
Statement Answer
True or False: Subscriptions are supported

automatically by OData feeds.
11-1
Module 11
Working with Business Data
Contents:
Lesson 1: Working with Business Data in Composite Solutions 11-2
Lesson 2: Working with Business Data in Custom Solutions 11-12
Lesson 3: Working with Business Data in Client Applications 11-26
Lab: Working with Business Data in Apps for SharePoint 11-36
Module Overview
In this module we will explore how Business Connectivity Services (BCS) integrates with other Microsoft®
SharePoint® front-end features such as external lists, external columns, and workflows. After looking at
how SharePoint out-of-box features work with BCS, you will learn how to integrate your own applications
with BCS solutions by using the various programming APIs provided. Additionally, we will look at how
Microsoft Office clients interact with BCS solutions and how that interaction is architected.
Objectives
 Access business data by using composite solutions.

 Utilize the Business Data Web Parts on your Team and Publishing pages.
 Work with external data columns in lists.
 Work with Business Data in SharePoint workflows.

 Access business data by using custom solutions.
 Utilize the various APIs available, such as CSOM, JSOM, and REST.
 Access business data by using client applications.

 Configure external content types for use with Office clients.
11-2 Working with Business Data
Lesson 1
Working with Business Data in Composite Solutions
In this lesson you will learn how SharePoint UI features interact with BCS solutions. One of the first things
you will explore is how to create external lists to leverage the same look and feel as native lists in
SharePoint, and to understand the differences between external lists and native lists. In addition, you will
see how native lists can utilize BCS data by using Business Data columns. Finally, you will learn how to
work with BCS data by using SharePoint 2010 and 2013 workflows.
Lesson Objectives
 Create external lists in SharePoint 2013.
 Use and customize Business Data Web Parts
 Create external data columns in custom lists.

 Create Business Data Actions.
 Describe the ways you can use Business Data in workflows.
Implementing External Lists

External lists are used to display, modify, delete, and
create items for an external content type. External
lists provide a mechanism for enabling access to
external content types, and thus access data on a
SharePoint site from anywhere on your network or
in the cloud. This access can be via the SharePoint
UI or via REST services, which you will learn about
later in this module.
There are two ways of creating external lists for a

content type:
 From SharePoint Designer. Once you create an

external content type in SharePoint Designer,
you can create an external list by simply clicking on Create Lists & Form on the Lists & Forms
section of the EXTERNAL CONTENT TYPE ribbon. When creating an external list by using this
method, you can specify whether to use custom InfoPath forms to view, edit, and create items in the
list.
 From a SharePoint site. You can add an external list as an app to any SharePoint site by using the add
an app link on the Site Contents page.
External lists provide several advantages for both developers and users. For example, external lists are:
 Easy to implement. Users can create an external list without the need for custom code.
 Easy to use. Users can work with external lists in the same manner that they interact with regular lists
in SharePoint.
 Easy to access from server-side code. Developers can access external lists by using the SPList class.
 Easy to access from client-side code. Developers can access external lists by using the CSOM and REST
API.
Things to watch out for

Although external lists expose your external business data, you should be careful when using external lists
that contain reference columns. SharePoint external lists are not feature rich enough to provide any type
of drop-down to allow users to select the proper value. For instance, if you have a reference column called
“State” that is an integer, the users must enter an integer rather than select “State” in a drop-down list.
You can resolve these limitations in various ways. The first is to be sure to create the proper Associator
methods between entities. This can provided a more enhanced experience for the users. But in addition to
creating the Associator, you must also be sure that you designate a “Title” column so the user sees a
meaningful selection rather than a number (“Alaska” instead of “1”). The second option is to de-normalize
the data in your back-end to something that can be easily consumed by SharePoint and users. The
process of de-normalization involves collapsing all the reference columns into their respective values.
Finally, another option is to create a custom InfoPath form that shows the user what options they have to
select before submitting the data to SharePoint.
You should also be aware that Business Connectivity Services is limited by the number of items it will
retrieve from the external system. By default, this limit is 2,000.
The following code example shows how you can use PowerShell to change the BDC throttling limits:
Changing the BDC Throttling Limits

$bdcAppProxy = Get-SPServiceApplicationProxy | where {$_ -match "Business Data
Connectivity Service"}
$throttleDb = Get-SPBusinessDataCatalogThrottleConfig -Scope Database -ThrottleType Items

-ServiceApplicationProxy $bdcAppProxy
Set-SPBusinessDataCatalogThrottleConfig -Identity $throttleDb -maximum 100000 -default

20000
$throttleConn = Get-SPBusinessDataCatalogThrottleConfig -Scope Global -ThrottleType

Connections -ServiceApplicationProxy $bdcAppProxy
Set-SPBusinessDataCatalogThrottleConfig -Identity $throttleConn -maximum 200 -default 150
Differences Between Native and External Lists

There are two different types of lists in SharePoint:
native and external. There are some functional
differences between the two that you should be
aware of. Most of these non-supported features
revolve around the fact that the data does not live
in SharePoint, and therefore SharePoint cannot
manage external data as it does data that it
controls. Although it is technically possible to
underpin an external list with a native list to support
these additional features, performance would be
sub-optimal, and therefore many of these features
may never be added to an external list.
Note: There are third-party ISVs that build synchronization tools that can bring data into
native SharePoint lists, which enables you to take advantage of SharePoint features for external
data.
For comprehensive information on the differences between native and external lists, please see:
Differences between native and external lists

Implementing Business Data Web Parts

You can provide access to an external content type
(ECT) instance by using Business Data web parts in
SharePoint 2013. These web parts require no code
and can be easily configured by users. Business data
web parts can take advantage of filters, methods,
and identifiers created for each ECT, and can be
used against any BDC application that has been
deployed to an associated BCS application.
The following business data web parts are available

out-of-the-box with SharePoint 2013:
 Business Data List. Displays a list of items and

entity instances from an ECT.
 Business Data Related List. Displays a list of items from an ECT that are related to a parent ECT.
Requires an association be created in the BDC model.
 Business Data Item. Displays a single item from an ECT.
 Business Data Item Builder. Creates an ECT item based on parameters from a URL string, and provides
it to other Business Data Web Parts.
 Business Data Actions. Displays actions for an ECT item.
 Business Data Connectivity Filter. Filters the content of a connected Business Data Web Part by using a
list of values from an ECT.
Each business data web part relies on the BDC model containing the supporting stereotyped methods. For
example:
 Business Data List requires the ReadItems method to be implemented.
 Business Data Related List requires an Association method to be configured
Business Data Web Part Properties

Each web part will have a series of properties, which in some cases must be configured and in other cases
are optional. For instance, the Business Data List web part must be configured to point to a specific BDC
registered model. Each web part has a different set of properties. You can find out more about each of
these properties here:
Use Business Data Web Parts

Combining Business Data models with external lists and business data web parts provides some very
interesting no-code solution possibilities. Some examples include:
 Display product data. You use the Business Data List to show products and their prices on a sales
representative’s support site.
 Implement master-child relationships. You can create a customer orders page that displays a list of
customers by using the Business Data List web part. You can then connect that web part to the
Business Data Related List web part to display a set of orders for a selected customer
 Entity Profile pages. You can create a CRM system that uses the primary key of the customer on an
ECT profile page to add a Business Data Item web part, but then also add custom web parts that do
other look ups to back-end data on the same page. All customer data can be put in one place for
employees in order to increase customer satisfaction when calling in to inquire about the status of
their account. Similarly, you can create a product page that shows all details of a product
 Search. Search will utilize profile pages that contain the Business Data Item web part to display
custom data when users click on the search result.
Creating Business Data Actions

When working with the entities in an External
Content Type, you may find that users are always
performing various actions once they find the data
entity they are looking for. These common Business
Data Actions can be implemented inside SharePoint
to help users be more efficient.
Business Data Actions are simply implemented as

links. This means you can use actions to perform
simple operations such as sending email messages
or opening a customer's home page. By default,
SharePoint will create a default action called “View
Profile” that is used to redirect a user to the entity
profile page. The entity profile page contains a Business Data Item web part that uses the query string to
look up the item and display its details.
To create new Business Data Actions, you can place them directly into the BDC model, or implement them
later by using the Business Connectivity Service application administration pages.
The following code example shows how to define Business Data Actions in the BDC model by using an
Actions element:
Defining a Business Data Action in a BDC Model

<Actions>
<Action Position="1" IsOpenedInNewWindow="true"
Name="Search"
DefaultDisplayName="Search on Bing"
Url="http://www.bing.com/search?q={0}"
ImageUrl="http://www.bing.com/s/wlflag.ico" >
<ActionParameters>
<ActionParameter Index="0" Name="ParameterName">
</ActionParameter>
</ActionParameters>
</Action>
</Actions>
When you enable an entity profile page, the default action will be set to the profile page URL. This is
required for when you integrate search results with your BCS solutions.
Links are formed by taking the columns defined in the entity and arranging them in a meaningful way.
Some examples of using Business Data Actions include:
 Use the email in an entity to create a “Send Email” link.
 Redirect a user to search for a commonly used property of an entity by using SharePoint search or an
external search provider such as Bing.
 Utilize entity keys to formulate a Business Intelligence report link.
Business Data Actions travel with the entity no matter where it is displayed. For example, Business Data
Actions are accessible from both Business Data Web Parts and Business Data Columns.
Working with External Data Columns

External data columns are columns that you can
add to any native SharePoint list to enable users to
pick data from an existing external content type.
For instance, you can deploy a BDC model that
exposes an ECT named Course to a given
SharePoint site. Then you can create a calendar list
in the site to schedule training. For each calendar
entry, you may want to show what course that entry
relates to.
External columns enable users to select only the

values that exist in the external system. This is
helpful when you want to enforce constraints on
users to pick only approved values, or to have a central repository for storing values that need to be
reused elsewhere. This is better than the alternative of creating the same choice column across many lists.
Note: Although a similar solution can be achieved with Managed Metadata columns, the
external system may be the system of record for the values and is more frequently updated.
When adding an item to the custom list, users will be able to retrieve a list of entities and view all fields in
the ECT that have the ShowInPicker property set to True in the BDC model.
Other common business data field scenarios include:
 Using external data to tag list content.
 Extending an external system with data stored in SharePoint.
 Forcing column constraints.
 Using Business Data in Office Clients such as Word.
To add an external column to any list in SharePoint, execute the following steps:
1. Open the list in the browser.
2. From the LIST ribbon, in the Settings group, click List Settings.
3. From the List Settings page, under Columns, click Create column.
4. From the Create Column page, in the Column name text box, type the name of the column to be
created.
5. From the list of column data types, select External Data.
6. To the right of the External Content Type text box, click the Select External Content Type button.
7. In the External Content Type Picker dialog box, select the ECT to use, and then click OK.
8. In the Select the field to be shown in this column drop-down list, select the field to be displayed in
the list, and then click OK.
Once you have created a business data column, you can then create items in a list by using values from
the ECT.
Demonstration: Using Actions and External Data Columns

The instructor will now demonstrate various ways in which you can work with external data without
writing custom code. You will see how to define and use actions on ECTs, and how to work with external
data columns.
Demonstration Steps
1. Open a File Explorer window and browse to E:\Democode\NorthwindService.
2. Right-click NorthwindService.sln, point to Open with, and then click Microsoft Visual Studio
2012.
3. Press F5 to start the service. This is an example OData service that provides data from a back-end
database.
4. Without closing Microsoft Visual Studio® or Internet Explorer, return to the Start screen, type Central
Administration, and then press Enter.
applications.
6. On the list of service applications, click Business Data Connectivity Service.

7. In the list of external content types, on the Customers drop-down menu, click Add Action.
8. On the Add Action page, in the Action Name box, type Search Company.
9. In the Navigate To This URL box, type

http://team.contoso.com/_layouts/osssearchresults.aspx?k={0}.
Note: You can also use external URLs in ECT actions. However, in a classroom environment
the virtual machine is not connected to an external network.
10. Under Launch the action in a new Web browser window (applies to External Data Web Parts
only), click Yes.
11. Under URL Parameters, click Add Parameter.
12. Under Parameter Property, in the drop-down list box, click CompanyName.
13. Select Default action, and then click OK.
14. Browse to http://team.contoso.com.
15. On the Settings menu, click Add an app.

17. In the Adding External List dialog box, in the Name box, type Customers.
18. Under External Content Type, click the Select External Content Type icon.
19. In the External Content Type Picker dialog box, click Customers, and then click OK.
21. On the Site Contents page, click Customers.
22. Verify that the Customers page displays several rows of data.
23. In any row, click the ellipsis, and then click Search Company.
24. Verify that Internet Explorer opens a new tab that displays a page named Search, where the search
text is the company name of the item you selected.
Note: The Search page will not display any results because the search service is not
configured on this virtual machine.
25. Close the Internet Explorer tab that contains the Search page.
26. On the Settings menu, click Add an app.
27. On the Your Apps page, click Custom List.
28. In the Adding Custom List dialog box, type CustomerExt, and then click Create.
29. On the Site Contents page, click CustomerExt.
30. On the ribbon, on the LIST tab, click Create Column.

31. In the Create Column dialog box, in the Column name box, type CustomerID.
32. Under The type of information in this column is, click External Data.
33. Under External Content Type, click the Select External Content Type icon.
34. In the External Content Type Picker dialog box, click Customers, and then click OK.
35. Under Select the Field to be shown on this column, in the drop-down list box, click CustomerID.
36. Under Add a column to show each of these additional fields, select CompanyName and
ContactName.
37. Click OK.
38. Click new item.
39. In the Title box, type Alfreds.
40. Next to the CustomerID box, click the Select External Item(s) icon.
41. In the Choose Customers dialog box, click ALFKI, and then click OK.
42. Click Save.
43. Verify that the external list displays data in the TestZ, TestZ: CompanyName, and TestZ: Maria
Anders columns.

Business Data and Workflows

It is possible to build workflows that interact with
External Lists. The activities you can perform are
limited to a very basic set of operations that revolve
around create, retrieve, update, and delete (CRUD).
You can also use the Set Workflow Variable
activity to get a value from an external list. The only
drawback is that you cannot directly associate a
workflow to an external list; the workflow must be
applied to a native list or at a site level.
When workflows execute against any type of list, it

must do so by using some identity. In the case of
external access, you can’t simply pass your local
SPUser account in an action that is wrapped by Impersonation. An SPUser account is something
SharePoint knows about, but an external system does not. Therefore, when accessing external lists, the
account is going to be some type of service account: either the application pool account of the web
application, the application pool account of the Business Connectivity Services service application, or
some other predefined account using Secure Store. This means you have only three supported
authentication methods that you can place in the BDC model file:
 Utilize Secure Store to retrieve the credentials to use.
 Use PassThrough (w3wp.exe).
 Use the RevertToSelf setting.
If you choose to use the BDC Identity, you will need to enable the Business Connectivity Service
Application to support the RevertToSelf method.
The following code example shows how you can use PowerShell to configure Business Connectivity
Services to use RevertToSelf authentication:
Enabling RevertToSelf Authentication

$bdc = Get-SPServiceApplication | where {$_ -match "Business Data Connectivity Service"};
$bdc.RevertToSelfAllowed = $true;
$bdc.Update();
Note: Using RevertToSelf authentication is not a best practice. The application pool
account used for most application pools will have a high level of privileges. These privileges
include being able to write farm configuration settings that most users should never be allowed
to have.
Using RevertToSelf authentication is not a best practice. The application pool account used for most
application pools will have a high level of privileges. These privileges include being able to write farm
configuration settings that most users should never be allowed to have.
For more information on the available authentication modes, see:
Authenticating to Your External System

To reiterate, even if you place the activities inside a workflow Impersonation step, the actual work will be
done via a service account or the Secure Store Identity. The user running the workflow will never have
their credentials passed to the external service.
Here are some helpful hints when working with workflows and business data:
 Attempting to read values that do not exist will return null.
 Creating an item in a workflow must use the identity that is returned to later make changes to the
item.
 Only the fields defined in the SpecificFinder method will be displayed in SharePoint Designer.
When you build Visual Studio workflows, you will utilize the Server or Client object model to interact with
external lists. These APIs are discussed in the next lesson.
Demonstration: Using Business Data in Workflows

The instructor will now demonstrate how you can work with external list data in a SharePoint site
workflow.
Demonstration Steps
1. Open a File Explorer window and browse to E:\Democode\NorthwindService.
2. Right-click NorthwindService.sln, point to Open with, and then click Microsoft Visual Studio
2012.
3. Press F5 to start the service. Explain that you have started an example OData service that provides
data from a backend database.
4. Without closing Visual Studio or Internet Explorer, open a new Internet Explorer window and browse
to http://team.contoso.com.
5. On the Quick Launch navigation menu, click Customers.

6. Explain that you will look up information from this list as part of a site workflow.
7. Point out that the first row of the list contains a CustomerID value of ALFKI, and that this
corresponds to a CompanyName value of Alfreds Futterkiste.
8. Close the current Internet Explorer window only.

11. In the Open Site dialog box, in the Site name box, type http://team.contoso.com, and then click
Open.
12. On the ribbon, click List Workflow. Point out that the Customers external list is not listed because
you cannot create list workflows for external lists.
13. On the ribbon, click Site Workflow.
14. In the Create Site Workflow dialog box, in the Name box, type External List Workflow.
Note: This demonstration uses SharePoint 2010 workflow mode for simplicity, because
using SharePoint 2013 workflow requires additional configuration that would place additional
load on the virtual machine. In a SharePoint 2013 workflow, you would use the Call Web Service
activity to interact with the external list through the REST API.
15. Click OK.
16. On the ribbon, in the Insert group, on the Action drop-down menu, click Set Workflow Variable.
17. Click workflow variable, and then click Create a new variable.
18. In the Edit Variable dialog box, in the Name box, type CompanyName.
19. In the Type drop-down list box, click String, and then click OK.
20. Click value, and then click fx.
21. In the Lookup for String dialog box, in the Data source drop-down list box, click Customers.
22. In the Field from source drop-down list box, click CompanyName.
23. In the Field drop-down list box, click CustomerID.
24. In the Value box, type ALFKI, and then click OK.
25. In the Microsoft SharePoint Designer dialog box, click Yes.

26. In the Step 1 box, click below the statement you just created.
27. On the ribbon, on the Action drop-down menu, click Log to History List.
28. Click this message, and then click fx.

29. In the Lookup for String dialog box, in the Data source drop-down list box, click Workflow
Variables and Parameters.
30. In the Field from source drop-down list box, click Variable: CompanyName, and then click OK.
31. On the ribbon, click Workflow Settings.
32. Under Start Options, ensure Allow this workflow to be manually started is selected.
33. On the ribbon, click Publish.
34. Open a new Internet Explorer window and browse to http://team.contoso.com.
35. On the Quick Launch navigation menu, click Site Contents.
36. On the Site Contents page, click SITE WORKFLOWS.

37. On the Workflows: Contoso Team Site page, click External List Workflow, and then click Start.
38. When the workflow has finished running, under My Completed Workflows, click External List
Workflow.
39. Point out that the Description column contains the value Alfreds Futterkiste. This is the company
name that corresponds to the customer ID you provided.

Lesson 2
Working with Business Data in Custom Solutions
Business Data can be accessed in several different ways. This plethora of different APIs enable your custom
applications to access back-end data and use it in ways other than as an external list, business data
column, or composite application. As with many other features of SharePoint, you can interact with
business data by using any of the standard APIs. In this lesson, you will learn how to use both server-side
and client-side code to interact with business data.
Lesson Objectives
 Describe the APIs available for working with Business Data.
 Build applications that utilize the Server, Client, JavaScript, and REST APIs.
 Describe the limitations of working with App-deployed BDC Models.

 Describe the limitations of the REST APIs.
 Learn to use the SPList class and its methods to interact with external lists.
Programmatically Working with Business Data

Business Connectivity Services and its multiple
features of External Lists, Business Data columns,
and support for event receivers and alerts are very
handy, but the real power is in the ability to write
your own applications that utilize SharePoint’s
Business Connectivity Services Layer.
Because of the variety of APIs that are offered, your

applications can be based on any platform and can
use any language that supports basic HTTP request
and responses. This means you can interact with
BCS ECTs from almost anywhere and at any time.
The various APIs available to you include:
 Server-side object model (OM). A set of .NET assemblies that must be run on a SharePoint server.
 Client-side object model (CSOM). A set of .NET assemblies that can be run on any .NET-supported
platform.
 JavaScript Object Model (JSOM). A set of JS libraries that you can use from SharePoint applications to
interact with your ECTs.
 REST API (REST). An HTTP-based API callable from any platform supporting HTTP.
When comparing the features available among external lists, business data web parts, and custom-built
applications using the various BDC APIs, only the BDC APIs give you full access to the capabilities that
BDC offers. For more information on the capabilities of the BDC APIs, see:
Using the BDC Object Model

http://go.microsoft.com/fwlink/?LinkID=327899
As you may have guessed, the applications you can build by using the BDC APIs are almost endless.
Office 365 Support
One of the biggest reasons the Client side object model and REST APIs exist is because you are not
allowed to deploy BCS solutions that have any supporting code (such as custom and .NET connectors) in
Office 365™. Additionally, you cannot deploy applications that utilize the server object model to Office
365. The only supported BDC models in Office 365 are solutions that use WCF service end points or
OData. Because of the unpredictability of the external data, currently Office 365 does not allow you to
index these BDC models.
You should keep these limitations in mind if you are considering developing BCS solutions and moving
from on-premise to Microsoft cloud-based solutions in the future.
Using the Server-Side Object Model

Rather than using SharePoint Designer to deploy
your ECTs, you can utilize the server-side object
model and its BDC classes to support manual
deployment via code. In addition to deployment,
you can also use the classes and their properties to
update the models and to execute the methods
contained within them.
The various BDC classes needed to deploy and

manipulate BDC models are defined in the
following namespaces on the
Microsoft.SharePoint.dll assembly:
 Microsoft.SharePoint.Administration;
 Microsoft.SharePoint.BusinessData.*;
You can create Business Data Models by using the server side object model:
Code to Create a Runtime BDC Model and Deploy it

// Get the Catalog for the SharePoint site
BdcService service =
SPFarm.Local.Services.GetValue<BdcService>(String.Empty);
SPSite site = new SPSite("<siteUrl>");
AdministrationMetadataCatalog catalog =
service.GetAdministrationMetadataCatalog(context);
// Create a new Contact Model

// NOTE: Assume that the "ContactModel" Model
// does not already exist.
Model contactModel = Model.Create(
"ContactModel", true, catalog);
// Make a new Contact LobSystem

// NOTE: Assume that the "AdventureWorks" LobSystem
// does not already exist.
LobSystem adventureWorksLobSystem =
contactModel.OwnedReferencedLobSystems.Create(
"AdventureWorks", true, SystemType.Database);
// Make a new AdventureWorks LobSystemInstance.

LobSystemInstance adventureWorksLobSystemInstance =
adventureWorksLobSystem.LobSystemInstances.Create(
"AdventureWorks", true);
// Set the connection properties.

adventureWorksLobSystemInstance.Properties.Add(
"AuthenticationMode", "PassThrough");
"DatabaseAccessProvider", "SqlServer");
"RdbConnection Data Source", "MSS2010");
"RdbConnection Initial Catalog", "AdventureWorks");
"RdbConnection Integrated Security", "SSPI");
"RdbConnection Pooling", "true");
// Create a new Contact Entity.

Entity contactEntity = Entity.Create(
"Contact",
"AdventureWorks",
true,
new Version("1.0.0.0"),
10000,
CacheUsage.Default,
adventureWorksLobSystem,
contactModel,
catalog);
// Set the identifier to the ContactID column.

contactEntity.Identifiers.Create(
"ContactID", true, "System.Int32");
// Create the Finder Method,

// i.e. the method to return all rows.
CreateReadListMethod(catalog, contactEntity);
// Create the Specific Finder Method,

// i.e. the method to return one row.
CreateReadItemMethod(catalog, contactEntity);
// Validate the Contact Entity.

ActivationError[] activationErrors =
contactEntity.Validate();
// Check if the validation failed.

if (activationErrors.Count() == 0)
{
// The validation was successful so publish the Contact Entity.
contactEntity.Activate();
Console.WriteLine("Created Contact Model");

}
else
{
// The validation failed so display the validation errors.
Console.WriteLine("Contact Model was not created and" +
" failed with the following errors:");
foreach (ActivationError item in activationErrors)
{
Console.WriteLine(item.ToString());
}
}
In addition to programmatically creating a model, you can deploy your pre-defined models by using
server-side object model.
Pre-created models can also be deployed programmatically:
Example of How to Deploy a Model by Using Server-side Code
string strModelName = "Contoso";

string strXmlFile = @".\" + strModelName + ".xml";
string siteUrl = "http://intranet.contoso.com/";

string strXmlData2Import;
string[] strarrNoncriticalErrors;
// Specify what to import: {"All", "InlineProxies",

// "LocalizedNames", "Model", "None", "Permissions",
// "Properties"}.
PackageContents packageContentsImportFlags =
PackageContents.All;
string strResourcesSettingId = "";

bool blUpdateExistingModel = false;
Guid guidJobId = new Guid("C6E88A92-31C2-4D02-9890-5DC2ADB36EA9");
try
{
// Get the model.
strXmlData2Import = File.ReadAllText(strXmlFile);
using (SPSite site = new SPSite(siteUrl))

{
// Reference the farm to host the BCS definitions.
using (new Microsoft.SharePoint.SPServiceContextScope(
SPServiceContext.GetContext(site)))
{
// Reference the BDC service.
SPFarm.Local.Services.GetValue<BdcService>
(String.Empty);
// Get the catalog of the referenced BDC service.

AdministrationMetadataCatalog cat =
service.GetAdministrationMetadataCatalog(
SPServiceContext.Current);
// Import the XML definition.

Model bcsadminModel = cat.ImportPackage(
strXmlData2Import,
out strarrNoncriticalErrors,
packageContentsImportFlags,
strResourcesSettingId,
blUpdateExistingModel,
guidJobId);
int iNumOfNoncriticalErrors =
strarrNoncriticalErrors.Length;
if (iNumOfNoncriticalErrors > 0)
{
Console.WriteLine("Noncritical Errors");
for (int iCtr = 0;
iCtr < iNumOfNoncriticalErrors;
iCtr++)
{
Console.WriteLine(
strarrNoncriticalErrors[iCtr]);
}
Console.WriteLine("Import completed successfully");

}
}
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
In addition to deploying BDC models, you can also work with them directly via the server object model.
This includes calling any of the stereotyped methods (such as the CRUD methods).
As part of the object model, you also have access to various helper methods such as the CreateDataTable
method that automatically populates a DataTable object with the query results from a Finder method.
Below are several examples of how to call various methods, but not all instances are included. To learn
more about how to make calls to all types of stereotyped methods from server side code, see:
Code Snippets: Executing Methods Using the BDC Runtime Object Model
Retrieving BDC Entities can also be achieved using the server object model:
Code that Gets a Specific Customer Entity by Using the SpecificFinder Method of a BDC Model
public IEntityInstance GetCustomersInstance(int customerId)

{
const string entityName = "Customers";
const string systemName = "CustomerManagement";
const string nameSpace = "DataModels.ExternalData.CustomerManagement";
BdcService bdcService = SPFarm.Local.Services.GetValue<BdcService>();

IMetadataCatalog catalog =
bdcService.GetDatabaseBackedMetadataCatalog(SPServiceContext.Current);
ILobSystemInstance lobSystemInstance =
catalog.GetLobSystem(systemName).GetLobSystemInstances()[systemName];
Identity identity = new Identity(customerId);
IEntity entity = catalog.GetEntity(nameSpace, entityName);
IEntityInstance instance = entity.FindSpecific(identity, lobSystemInstance);
return instance;
}
You can call the creator method in your models from server side code:
Example of How to Call a Creator Method to Create a New Entity in the External System
string SiteURL = "http://teams.contoso.com";

string nameSpace = "Contoso.Customers";
string entityName = "Customers";
using (SPSite site = new SPSite(SiteURL))

{
{
SPFarm.Local.Services.
GetValue<BdcService>(String.Empty);
service.GetDatabaseBackedMetadataCatalog(
IEntity entity =
catalog.GetEntity(nameSpace, entityName);
ILobSystemInstance LobSysteminstance =
entity.GetLobSystem().
GetLobSystemInstances()[0].Value;
IView createView = entity.GetCreatorView("Create");

IFieldValueDictionary fieldValueDictionary =
createView.GetDefaultValues();
fieldValueDictionary["CustomerID"] = "JDOE";
fieldValueDictionary["FirstName"] = "John";
fieldValueDictionary["LastName"] = "Doe";
fieldValueDictionary["ModifiedDate"] = DateTime.Now;
Identity id = entity.Create(fieldValueDictionary,
LobSysteminstance);
}
}
}
You can also retrieve entity instances by calling Finder methods:
Server-Side Code that Retrieves a Set of Entities by Using a Finder Method

string SiteURL = "<siteUrl>";
string nameSpace = "<nameSpace>";
string entityName = "<entityName>";
using (SPSite site = new SPSite(SiteURL))

{
{
SPFarm.Local.Services.GetValue<BdcService>(
String.Empty);
service.GetDatabaseBackedMetadataCatalog(
IEntity entity = catalog.GetEntity(

nameSpace, entityName);
ILobSystemInstance LobSysteminstance =
entity.GetLobSystem().
GetLobSystemInstances()[0].Value;
// Display the fields in the Entity.

IFieldCollection fieldCollection =
entity.GetFinderView("Read List").Fields;
foreach (IField field in fieldCollection)

{
Console.Write(field.Name.PadRight(20));
}
// Display all the records in the Entity.

IMethodInstance methodInstance = entity.GetMethodInstance(
"Read List", MethodInstanceType.Finder);
IEntityInstanceEnumerator ientityInstanceEnumerator =
entity.FindFiltered(methodInstance.GetFilters(),
LobSysteminstance);
while (ientityInstanceEnumerator.MoveNext())
{
foreach (IField field in fieldCollection)
{
Console.Write(
ientityInstanceEnumerator.
Current[field.Name].ToString().PadRight(20));
}
Console.WriteLine();
}
}
Console.ReadKey();
}
Finder methods can allow you to find entities based on a set of filer parameters:
Example of How to Call a Finder Method with Filter Parameters

public DataTable FindOrdersForCustomers(string customerId)
{
IFilterCollection filters = entity.GetDefaultFinderFilters();
if (!string.IsNullOrEmpty(customerId))
{
WildcardFilter filter = (WildcardFilter)filters[0];
filter.Value = customerId;
}
IEntityInstanceEnumerator enumerator =
entity.FindFiltered(filters, lobSystemInstance);
return entity.Catalog.Helper.CreateDataTable(enumerator);
}
You can make calls to the Association methods by using the Server Object Model:
Calling an Association Method

public DataTable GetOrdersForCustomer(int customerId)
{
// Retrieve the association method.

IAssociation association = (IAssociation)entity.GetMethodInstance(
"GetOrdersForCustomer", MethodInstanceType.AssociationNavigator);
Identity identity = new Identity(customerId);

// Retrieve an entity instance.

IEntityInstance customerInstance =
entity.FindSpecific(identity, lobSystemInstance);
EntityInstanceCollection collection = new EntityInstanceCollection();
collection.Add(customerInstance);
// Navigate the association to get parts.

IEntityInstanceEnumerator associatedInstances = entity.FindAssociated(
collection, association, lobSystemInstance, OperationMode.Online);
return entity.Catalog.Helper.CreateDataTable(associatedInstances);
}
Updating Business Data Columns

As mentioned in the previous lesson, you can add Business Data columns to native SharePoint lists. When
working through the SharePoint UI, updating these items is very simple. However, when it comes to
programmatically working with these columns, it can be a bit tricky. The following is an example of how
to update a Business Data Column in an external list.
Updating a Business Data Column in a native list is not straightforward:
How to Update a Business Data Column in a Native SharePoint List

//Get the entityInstance from BDC
//Get the listitem from the list
SPBusinessDataField dataField = listItem.Fields["BCSField"] as SPBusinessDataField;

listItem[dataField.RelatedField] = customerId;
DataTable dtEntityData = entityInstance.EntityAsFormattedDataTable;

listItem[dataField.Id] = dtEntityData.Rows[0][dataField.BdcFieldName].ToString();
IMethodInstance method =
entityInstance.Entity.GetMethodInstances(MethodInstanceType.SpecificFinder)[0].Value;
ITypeDescriptorCollection oDescriptors =
method.GetReturnTypeDescriptor().GetChildTypeDescriptors()[0].GetChildTypeDescriptors();
foreach (ITypeDescriptor oType in oDescriptors)

{
if (oType.ContainsLocalizedDisplayName())
{
if (dtEntityData.Columns.Contains(oType.Name))
{
dtEntityData.Columns[oType.Name].ColumnName = oType.GetLocalizedDisplayName();
}
}
}
string[] sSecondaryFieldsDisplayNames = dataField.GetSecondaryFieldsNames();
foreach (string columnNameint in sSecondaryFieldsDisplayNames)

{
Guid fieldID = listItem.Fields[String.Format("{0}: {1}", dataField.Title,
columnNameint)].Id;
listItem[fieldID] = dtEntityData.Rows[0][columnNameint].ToString();
}
listItem.UpdateOverwriteVersion();
Using the Client-Side Object Model

Just as you can do in the server-side object model,
you can use the client-side object model to retrieve,
update, and manage external content types
exposed by BCS. Developers can use the client
model by using a special set of .NET assemblies in
their non-SharePoint hosted applications. These
provided .NET assemblies enable you to access
external content types by using any type of .NET
client application (Console, WCF service, Windows,
etc.).
These client-side assemblies are located in the

SharePoint Root folder at C:\Program
Files\Common Files\Microsoft Shared\Web Server Extension\15\ISAPI. The specific client side assemblies
needed are:
 Microsoft.SharePoint.Client.Runtime.dll
 Microsoft.SharePoint.Client.dll
For a complete look at all the available classes and methods available in the BDC CSOM, see:
BCS client object model reference for SharePoint 2013

Using the .NET Client-Side Object Model

You can use the CSOM to do many of the things you learned to do in the server-side object model, but
not everything. One such case is deploying a model. This cannot be done by using CSOM, and must be
part of an application deployment process. However, once you have deployed a model, you can use the
.NET client-side object model to do CRUD methods and execute other named methods in the model.
You can retrieve a reference to an external content type by using the GetEntity method:
An Example Code Segment Used to Retrieve an Entity Definition Called Product From a SharePoint
Site
ClientContext ctx = new ClientContext("http://team.contoso.com");
Web web = ctx.Web;
ctx.Load(web);
Entity entity = ctx.Web.GetEntity("http://team.contoso.com", "Product");
ctx.Load(entity);
ctx.ExecuteQuery();
Once you have a reference to an entity object, you can call any method exposed by the external content
type by name, as shown in this code snippet.
You can run any method exposed by an external content type by name:
An Example of Running a Method From an External Content Type by Name

ObjectCollection products;
entity.Execute(“ReadList”, northwindLobSystem, products);
ctx.Load(products);
ctx.ExecuteQuery();
The code segment above retrieves all instance of the Product external content type. One of the issues of
writing code similar to the one above is the fact that the external content type may contain thousands or
even millions of instances. Usually, you will retrieve instances by using filters, and even then bring in only a
certain number of instances at a time.
You can use filters exposed by an external content type to retrieve instances from the entity:
An Example of Using a Filter on the Product External Content Type to Retrieve Data.
FilterCollection productFilters = entity.GetFilters(“ReadList”);
ctx.Load(productFilters);
ctx.ExecuteQuery();
FilterCollection modifiedProductFilters = new FilterCollection();

foreach(Filter filter in productFilters)
{
if(filter.FilterField.equals(“Category”))
{
filter.FilterValue = “Printers”;
modifiedProductFilters.Add(filter);
}
}
EntityInstanceCollection eCollection = entity.FindFiltered(modifiedProductFilters,

“ReadList”, northwindLobSystem);
ctx.ExecuteQuery();
The code segment uses a filter to reduce the number of instances retrieved from the entity. However, we
still do not have control over how many instances are being retrieved. You can limit the number of
instances retrieved by using paging.
You can use limit filters to retrieve a specific set of instances for a given entity:
An Example of Using a Limit Filter

FilterCollection productFilters = entity.GetFilters(“ReadList”);
ctx.Load(productFilters);
ctx.ExecuteQuery();
FilterCollection modifiedProductFilters = new FilterCollection();
foreach(Filter filter in productFilters)
{
if(filter.FilterField.equals(“Category”))
{
filter.FilterValue = “Printers”;
}
if(filter.FilterType == FilterType.Limit)
{
filter.FilterValue = 50;
}
}
EntityInstanceCollection eCollection = entity.FindFiltered(modifiedProductFilters,
“ReadList”, northwindLobSystem);
ctx.ExecuteQuery();
Using the JavaScript Object Model

The JavaScript Object Model (JSOM) exposes all of
the classes and methods that the Client Side Object
Model (CSOM) does in terms of BCS support. This
means that you can work with ECTs from
SharePoint Apps. This includes calling stereotyped
methods that perform CRUD operations. The only
drawback to working with Apps that deploy ECTs is
that this mode of deployment will not allow you to
use the basic CSOM or JSOM methods, because the
ECT is actually defined in the App Web and not in
the Business Connectivity Services service
application. This is called in-memory BCS. Because
of this, the way you can interact with the ECT is a bit limited. In most cases you will create an external list
from the ECT and then make REST calls to the ECT, just as you would any other native SharePoint list.
As you may know, the new App Model in SharePoint 2013 is the recommended way for building
applications that extend and add functionality to SharePoint. When you build an App for SharePoint and
choose to work in JavaScript, most of the time you will be working with your JavaScript code via the
App.js file. Although you can certainly have more .js files, this file is provided by the App for SharePoint
project template as a starting point.
JSOM is exposed by a series of JavaScript files on the web server, the main file being SP.js. It contains
various namespaces that deal with external content types. By using tools such as .NET Reflector, you can
find the available methods of the various Client OM BCS related classes in the
Microsoft.SharePoint.BusinessData.MetadataModel.ClientOM namespace of the Microsoft.SharePoint.dll.
In this namespace you will find a class called Entity that has the following CSOM and JSOM exposed
methods:
 BuildEntityInstanceCollection(IEntityInstanceEnumerator entityInstances);
 Create(FieldValueDictionary fieldValues, LobSystemInstance lobSystemInstance);

 Execute(string methodInstanceName, LobSystemInstance lobSystemInstance, object[] inputParams);
 FindAssociated(AbstractEntityInstance entityInstance, string associationName, FilterCollection

filterList, LobSystemInstance lobSystemInstance);
 FindFiltered(FilterCollection filterList, string nameOfFinder, LobSystemInstance lobSystemInstance);
 FindSpecific(Identity identity, string specificFinderName, LobSystemInstance lobSystemInstance);
 FindSpecificByBdcId(string bdcIdentity, string specificFinderName, LobSystemInstance

lobSystemInstance);
 FindSpecificDefault(Identity identity, LobSystemInstance lobSystemInstance);
 FindSpecificDefaultByBdcId(string bdcIdentity, LobSystemInstance lobSystemInstance);

 GetAssociationView(string associationName);
 GetCreatorView(string methodInstanceName);
 GetDefaultSpecificFinderView();
 GetFilters(string methodInstanceName);
 GetFinderView(string methodInstanceName);
 GetIdentifierCount();
 GetIdentifiers();
 GetLobSystem();
 GetSpecificFinderView(string specificFinderName);
 GetUpdaterView(string updaterName);
 Subscribe(NotificationCallback notificationCallback, string onBehalfOfUser, string subscriberName,]

LobSystemInstance lobSystemInstance);
 Unsubscribe(Subscription subscription, string onBehalfOfUser, string unsubscriberName,

LobSystemInstance lobSystemInstance);
Using the Business Data REST API

One of the new features in SharePoint 2013 is the
ability to access both native and external lists by
using the REST API. Because REST is a simple HTTP
protocol, you can use the REST API from pretty
much anywhere, including JavaScript or .NET code.
The code segment below shows how to access data

from an entity named Product by using the REST
API from JavaScript.
You can use the REST API from JavaScript to access

data from an external list:
An Example of Using the REST API to Access an External List

// Namespace
window.AppLevelECT = window.AppLevelECT || {};
// Constructor
AppLevelECT.Grid = function (hostElement, surlWeb) {
this.hostElement = hostElement;
if (surlWeb.length > 0 && surlWeb.substring(surlWeb.length - 1, surlWeb.length)
!= "/")
surlWeb += "/";
this.surlWeb = surlWeb;
}
// Prototype
AppLevelECT.Grid.prototype = {
init: function () {
$.ajax({
url: this.surlWeb +
"_api/lists/getbytitle('Product')/items?$select=BdcIdentity,ProductID,ProductName",
headers: {
"accept": "application/json",
"X-RequestDigest": $("#__REQUESTDIGEST").val()
},
success: this.showItems
});
},
showItems: function (data) {
var items = [];
items.push("<table>");
items.push('<tr><td>Product ID</td><td>Product Name</td></tr>');
$.each(data.d.results, function (key, val) {
items.push('<tr id="' + val.BdcIdentity + '"><td>' +

val.ProductID + '</td><td>' +
val.ProductName + '</td></tr>');
});
items.push("</table>");
$("#displayDiv").html(items.join(''));
}
}
ExecuteOrDelayUntilScriptLoaded(getProducts, "sp.js");
});
function getProducts () {
var grid = new AppLevelECT.Grid($("#displayDiv"),
spPageContextInfo.webServerRelativeUrl);
grid.init();
}
Note: The REST API can only be used to access external content types by using an external
list.
Using SPList with External Lists

SharePoint apps use the client-side object model to
work with external content types. However, you can
still develop simple SharePoint solutions that use
basic server-side code. In other words, you can use
the SPList class to access external lists and retrieve,
modify, create, and delete instances of an external
content type as a list item. The code below shows
an example of retrieving data from an external list
by using the SPList class.
The following code example shows how to use the

SPList class to retrieve data from an external list:
Retrieving Data from an External List

using(SPSite site = new SPSite("http://team.sharepoint.com"))
{
SPWeb web = site.OpenWeb();
SPList list = web.Lists["Product"];
foreach(SPListItem item in list.Items)
{
Console.WriteLine(item["ProductName"].ToString())
}
}
The following code example shows how to use the SPListItem class to update items in an external list:
Updating Items in an External List

{
{
if (item["ProductName"].ToString() == “Printer”)
{
item[“ProductName”] = “Printing Device”;
item.Update();
}
}
}
The following code example shows how to create items in an external list by using the SPList and
SPListItem classes:
Creating Items in an External List

{
SPListItem item = list.Items.Add();
item[“ProductName”] = “Printing Device”;
item.Update();
}
The following code example shows how to use the SPList and SPListItem classes to delete items in an
external list:
Deleting Items in an External List

{
{
if (item["ProductName"].ToString() == “Printer”)
{
item.Delete();
}
}
}
The examples above retrieve all items from an external list. In real life, you would use CAML or filters to
retrieve only a limited set of items.
Lesson 3
Working with Business Data in Client Applications
In this lesson you will learn to how BCS solutions can be used by Office client-side applications such as
Microsoft Outlook®, Word, and Visio®. In addition, you will learn how these client-side applications
utilize a client-side runtime and client-side cache with subscriptions to keep data stored locally, and how
this client-side runtime architecture synchronizes changes back to the external systems.
Lesson Objectives
 Describe typical scenarios where external data can be accessed from Office applications.
 Describe the BCS architecture for Office clients.
 Describe the use of the client-side cache.
 Programmatically work with the client-side cache.

 Implement cache subscriptions.
 Deploy ECTs to Office clients.
Overview of Typical Scenarios

SharePoint is a part of the Office group at Microsoft
and as such, most product features must be able to
interact with other Office products. This is also true
in the case of Business Connectivity and Office
client applications. Office client applications such as
Outlook, Word, and even Visio, can connect to BCS
applications to retrieve and use data exposed by a
BDC model. There are several prerequisites and
limitations for this integration, but it allows the use
of BCS data beyond SharePoint sites and apps.
Note: Microsoft Excel® does not provide any

built-in capabilities for interacting with external lists. However, you can still develop custom add-
ins for Excel that work with external lists.
Some examples of using BCS to integrate with Office client applications include:
 Import a set of client contacts from your CRM system into your Outlook client.
 Automate the creation and populate of form and document data by using business data.
 Implement a color map on a Visio diagram based on values in the back-end database.
Working with BCS Client Runtime

The BCS Client Runtime is a connector between BCS
solutions and Microsoft Office client applications.
After an external data model has been deployed it
can be brought into Office applications and shown
contextually. In order for this to work, the BDC
model must have a mapping of the external data to
the different Office application user interface (UI)
elements.
The BCS Client Runtime loads every time that the

host Office application loads, and it raises, listens to,
and acts on specific events generated on the host
application. An in-memory Microsoft SQL Server
Compact database on the client maintains the metadata and the cached entities that are of interest to the
user. This architecture enables solution developers to focus on solving business needs, instead of handling
the complexity of interacting with BCS. This runtime runs on the client side and is installed as part of the
Office Professional client install.
When an office application makes a call to Business Data, it typically will do so through a BCS Client
Runtime in a process that works like the following:
1. User tries to access ECT and Office makes a request.
2. Request is passed to BDC Client Runtime.
3. BDC Client Runtime queries the BDC model in the BDC client-side cache.
4. If credentials are needed, user is prompted for them, and credentials are stored.
5. BDC Client Runtime passes the request to the appropriate connector.
6. Data is retrieved from external data source and passed up the chain.
Understanding the BCS Client Cache

Business Connectivity Services (BCS) uses a local
client cache to store a copy of the external data
required by BCS solutions in Office client
applications. The cache enables external data to be
automatically copied on the client and accessed
offline. The BCS client runtime ensures that data
synchronization between the cache and the external
application is performed. By implementing this
caching layer, you gain the following advantages:
 Increased application throughput. After the data

is stored in the cache, it can be used by
accessing the cached copy instead of re-
fetching the original data from the external business application.
 Support for disconnected scenarios. Users can continue to manipulate external data seamlessly and
efficiently, even when connectivity is slow, intermittent, or unavailable.
The client cache persistence store is implemented as a SQL Compact Edition database. The database cache
works at an entity level, which means that you can store one entity or many specified entities, but not
parts of entities. When the cache is running, you will notice a process called BCSSync.exe running on your
client computer. It is the job of this process to provide automatic cache refresh and data synchronization
of the entity instances.
Whenever an operation such as Read, Create, Update, or Delete is performed on an entity instance in the
client application, calls are not routed directly to the external application. Instead, operations are stacked
in a queue and then executed one-by-one depending on the availability of the external application. The
BCSSync.exe process also tries to refresh the cache from the external application at certain intervals.
However, the exact time at which the cache is refreshed cannot be predicted and depends on several
factors.
Note: You should not edit the cache database directly. Instead, you should use the Cache
object model to get access to the client cache.
Populating the Cache

To populate the cache for a subscription, the BCSSync.exe process makes several calls to the external
application. For each query defined in the subscription, it makes a Finder call to the external application. If
the Finder returns the full view, no additional calls are made and the cache is populated with the data
about each entity instance. However, if the Finder does not return the full view, then it populates the
cache with the IDs from the Finder. Subsequently, for any non-cached identifiers that are returned by the
query, a SpecificFinder call is made to get the fields returned.
The BCSSync.exe process makes as many SpecificFinder calls as there are explicit identities in the
subscription, and populates the cache with the entity instances that are returned by the method instance.
Finally, it populates the cache with related entity instances if there are any enabled associations in the
subscription. To do this, it makes as many Associate method instance calls as there are entity instances in
the cache for this subscription. This returns the IDs of the related entity instances. Then it calls the
SpecificFinder on each of the returned IDs to fetch the other fields.
Working with Cache Subscriptions

Using the BCS Client Cache can improve the
performance of your Office clients. However, it is
impractical to cache every single item in a back-end
external data source. It is especially true when your
back-end data source has several million items. To
help alleviate the possibility of caching millions of
items, you can tell the BCS Client Cache to
download only items you are interested in. These
are called Cache Subscriptions.
Cache Subscriptions
A subscription defines what data gets populated in the client cache and is automatically generated by BCS
during deployment of a BCS solution. It is represented as an XML file (subscription.xml) and can be found
in the deployment folder. Although a subscription is auto-generated at deployment time, you can modify
a subscription programmatically by using the object model. Subscriptions contain the following objects:
 Queries. The queries (Finders) that must be executed to get the entity instances into the client cache.
The following list provides sample queries:
o GetCustomers,filter value = WA (returns customers from Washington)
o GetProducts,filter value = Computers (returns products that are part of the Computers category)
 Explicit identities. Any additional entity instances that you want to bring from the external data source
by providing their identities explicitly. For instance, you can edit the .xml subscription file and add an
entry to retrieve product #23 (where 23 is the unique identifier for the product).
 Subscription association. A subscription association is an AssociationNavigator method instance that

can be used to retrieve data from the BDC model.
The XML fragment below is an example of a cache subscription:

<Subscription LobSystemInstanceName="AdventureWorksContosoLOBInstance"
EntityNamespace="AdventureWorksContoso" EntityName="Customer"
Name="AdventureWorksContosoCustomerSubscription" View="GetCustomerById"
IsCached="true" RefreshIntervalInMinutes="360"
xmlns="http://schemas.microsoft.com/office/2006/03/BusinessDataCatalog">
<Identities>
<Identity>234</Identity>
<Identity>752</Identity>
</Identities>
<Queries>
<Query Name="AdventureWorksContosoCustomerQuery"
MethodInstanceName="GetCustomers"
DefaultDisplayName="Customer Read List"
RefreshIntervalInMinutes="180" IsCached="true" Enabled="true">
<FilterValues>
<FilterValue FilterDescriptorName="MinCustomerId" FilterIndex="0"
Type="System.Int32">11050</FilterValue>
</FilterValues>
</Query>
</Queries>
</Subscription>
You can programmatically edit the subscription file to add or remove items:
How to Work with the Subscription file

RemoteOfflineRuntime remoteOfflineRuntime = new RemoteOfflineRuntime();
ISubscription sub = remoteOfflineRuntime.GetSubscriptionManager().GetSubscription(

"<entityNamespace>", "<entityName>", "<viewName>", "<subscriptionName>");
sub.ExpireAfter = new TimeSpan(0, 30, 0);

sub.Update();
foreach (ISubscriptionQuery query in sub.Queries)

{
if (query.Enabled == false)
{
query.Enabled = true;
}
query.ExpireAfter = TimeSpan.FromMinutes(10);
query.Update();
}
foreach (ISubscriptionAssociation association in sub.Associations)

{
if (association.Enabled == false)
{
association.Enabled = true;
}
association.ExpireAfter = TimeSpan.FromMinutes(10);
association.Update();
Programming the BCS Client Cache

When building your own Office applications, you
can work with the client cache directly via the
Microsoft.BusinessData.Offlining namespace.
When working with the BCS client runtime object

model, you can configure the operation mode to
tell the BCS client runtime how you want to use the
cache. BCS supports two kinds of cache usage
modes:
 Online. In this mode, the cache is not used. All

the calls to the external data source such as
Read, Update, and so forth, are routed directly
to the external data source via the Business
Data Connectivity (BDC) runtime.
 Cached. In this mode the cache is used. Cache is populated with the entity instances from the external
data source at deployment time and data is refreshed from the external data source at specified
intervals. Operations are not immediately routed to the external data source, but are routed to the
cache. The cache puts these operations in the operation queue and executes them one-by-one.
Cache Read Operations

When the BCS runtime is in Cached mode, each entity will have a status that will determine how the item
is read from the cache. These include:
 Fresh. The entity was just received from the external source and the cache refresh interval has not
passed
 Invalid. The data is not useful and a refresh of the entity via the SpecificFinder method should be
performed
 Obsolete. The runtime that the BCSSync.exe process has already been notified that it must refresh the
entity based on changes in the external system
 Stale. The entity is due to be refreshed, but the BCSSync.exe has no reason to believe the entity has
changed
Refreshing the Cache

The runtime cache will update entities based on their ExpireAfter internal. Once the interval has passed,
the BCSSync process must execute a sync. The refresh is not guaranteed to run at the ExpireAfter interval.
Pending operations are executed before any cache refreshes. Therefore, you really won’t know when the
cache actually gets refreshed. Once it does start a refresh operation, the items that have the longest
expiration will be executed first, until all subscriptions are refreshed. In addition to the ExpireAfter
setting, you can also request that an entity be refreshed explicitly through code.
For more information on the BCS Client Runtime Cache, see:

Understanding Business Connectivity Services Client Cache to Optimize Your Solutions
You can work with the client cache programmatically to retrieve entities when the client is offline. The
following code example shows how to enumerate the items in an ECT in the client cache:
Enumerating Items in an ECT in the Client Cache

RemoteSharedFileBackedMetadataCatalog catalog = new
RemoteSharedFileBackedMetadataCatalog();
INamespacedEntityDictionaryDictionary entDictDict = catalog.GetEntities("*");
foreach (INamedEntityDictionary entDict in entDictDict.Values)
{
foreach (IEntity entity in entDict.Values)
{
entityDictonary.Add(entity.Name, entity);
}
}
IEntity entity = entityDictonary[0];

IEntityInstanceEnumerator instanceEnumerator = entity.FindFiltered(
entity.GetDefaultFinderFilters(),
entity.GetMethodInstances(MethodInstanceType.Finder)[0].Value.Name,
entity.GetLobSystem().GetLobSystemInstances()[0].Value,
OperationMode.CachedWithoutRefresh);
DataTable dt = new DataTable();

string finderName = entity.GetMethodInstances(MethodInstanceType.Finder)[0].Value.Name;
IView v = entity.GetFinderView(finderName);
foreach (IField f in v.Fields)
{
dt.Columns.Add(new DataColumn(f.Name, Type.GetType(f.TypeDescriptor.TypeName)));
}
while (instanceEnumerator.MoveNext())
{
IEntityInstance iei = instanceEnumerator.Current;
DataRow dr = dt.NewRow();
foreach (IField f in v.Fields)
{
dr[f.Name] = iei[f.Name];
}
dt.Rows.Add(dr);
}
You may have instances where you need to programmatically request the BCSSync.exe service to refresh
the cache:
How to Request a Cache Refresh from the Office Client Application

RemoteOfflineRuntime offlineRuntime = new RemoteOfflineRuntime();
ISubscriptionManager subManager = offlineRuntime.GetSubscriptionManager();
ISubscription sub = subManager.GetSubscription("<EntityNameSpace>", "<EntityName>",
"<ViewName>", "<SubscriptionName>");
sub.RequestRefresh(true);
Configuring ECTs to support Office Clients
You have been introduced to some typical scenarios

for using Business Data ECTs in Office Applications.
Here you are given the steps necessary to set up
each scenario with respect to each Office Client. No
matter what client you are working with, you must
perform a basic series of steps:
1. Prepare the external data source. Provide access
to a new or existing data source that contains
the data to be accessed. This can be a SQL
Server database or OData service. Make sure
you have an account with sufficient rights to
read the data being exposed in the data source.
2. Configure SharePoint services and accounts. Add and configure Business Data Connectivity Services
and Secure Store Services. Make sure you create an application in Secure Store Services that maps to
the required account or accounts needed to access the external data source.
3. Configure Business Data Connectivity Services. Make sure BCS is configured to allow users who will
create external content types to add metadata to BCS.
4. Activate the Offline Synchronization for External Lists feature. This must be done on each SharePoint
web. If it is not completed, you will not see the ability to Connect the external lists to office client
applications
Outlook
One of the easiest applications to integrate with BCS data is Outlook. You can easily access external lists
from within Outlook, as long as the external lists expose an external content type (ECT) that is Office
compatible. The overall process for allowing access to an external list from Outlook is the following:
1. Create an external content type. Create an Outlook-supported external content type. Office-
supported content types must have the Offline Sync support option enabled, and they must be
created by selecting an Office Item Type for the external content type when creating the ECT by
using SharePoint Designer. The following Office item types are supported:
a. Appointment
b. Contact
c. Post
d. Task
2. Map corresponding fields. You must map the fields available in the ECT with fields expected for the
selected Office item type. Not all fields must be mapped, but you must map the following fields by
Office item type:
a. Appointment: Subject
b. Contact: LastName
c. Post: Subject
d. Task: Start, End, and Subject
3. Create an external list. You must create an external list based on the new ECT to allow Outlook to
access it.
4. Install Office prerequisites for using BCS. Client computers must be running Windows 7 or later with
SQL Server Compact 4.0, .NET Framework 4, and WCF Data Services 5.0 for OData V3.
5. Connect the external list to Outlook. Navigate to the newly create external list and from the List
ribbon, click Connect to Outlook.
Note: The Connect to Outlook button may not do anything when you click it. This is due
to your SharePoint site not being trusted by the browser.
Word
You can use QuickParts in Word to expose data from columns added to a document library. These
columns can contain any type of data available to SharePoint, including external content type. The
process for making an ECT available to Word documents is the following:
1. Create an external content type. Create the ECT by using SharePoint Designer, custom code, or
importing a BDC model. In this case, you do not need to specify any special type of Office item type.
2. Create a document library. Create a document library that uses a Word document as a template.
3. Add a column to the document library. Change the document library settings and add a new column
of type External data that maps to the ECT you want to use.
4. Edit the template used in the document library. From the document library settings, click Advanced
settings, and then click Edit Template. Once the template is open in Word, from the Insert ribbon,
click Quick Parts, navigate to Document Property, and then click on the name of the column you
added to the document library. Save and close the template.
5. Create a new document. Create a new document in the document library and notice that the
document property added has a button named Select. When you click the Select button, the ECT
item picker is displayed.
Note: You cannot modify values in an ECT from Word.
Visio
You can add data from any list in SharePoint to Visio. Therefore, to add from an ECT in a Visio diagram, all
you need to do is create an external list based on an ECT, and then in a Visio file, link data to any shape.
The overall process for adding ECT data to Visio diagrams is the following:
1. Create an external content type. Create the ECT by using SharePoint Designer, custom code, or
importing a BDC model.
2. Create an external list. You must create an external list based on the new ECT to allow Outlook to
access it.
3. Install Office pre-requisites for using BCS. Client computers must be running Windows 7 or later with
SQL Server Compact 4.0, .NET Framework 4, and WCF Data Services 5.0 for OData V3.
4. Add ECT data to a Visio diagram. Open a Visio diagram, or create a new one, and from the Data
ribbon, click Link Data to Shapes, and then select Microsoft SharePoint Foundation.
Demonstration: BCS and Office Clients

The instructor will now demonstrate how to create an ECT that supports Outlook contact types, and how
to connect a compatible external list to an Outlook client.
Demonstration Steps
3. In the Open Site dialog box, in the Site name box, type http://team.contoso.com, and then click
Open.
5. In the navigation pane, click External Content Types.
7. In the External Content Type Information pane, next to Name, click New external content type.
8. Type Customer Contacts, and then press Tab.
9. In the Office Item Type drop-down list box, click Contact.
10. In the External Content Type Operations pane, click Click here to discover external data sources
and define operations.

12. In the External Data Source Type Selection dialog box, in the Data Source Type drop-down list
box, click SQL Server, and then click OK.
13. In the SQL Server Connection dialog box, in the Database Server box, type London.
15. Click Connect with Impersonated Windows Identity, and then in the Secure Store Application ID
box, type ContosoDW.
16. Click OK.
17. In the BCS Secure Store : ContosoDW dialog box, in the User name box, type
18. In the Password box, type Pa$$w0rd, and then click OK.
19. On the Data Source Explorer tab, expand ContosoRetailDW, and then expand Table.
20. When the Microsoft SharePoint Designer dialog box appears, explain that the unsupported types
will not affect the demonstration, and then click OK.
21. Under Tables, right-click DimCustomer, and then click Create All Operations.
22. In the All operations dialog box, click Next.

23. Under Parameters Configuration, click FirstName (the text, not the check box).
24. In the Properties pane, in the Office Property drop-down list box, click First Name (FirstName).
25. Under Parameters Configuration, click LastName (the text, not the check box).
26. In the Properties pane, in the Office Property drop-down list box, click Last Name (LastName),
and then click Next.
27. On the Filter Parameters Configuration page, click Add Filter Parameter.
28. In the Properties pane, next to Filter, click Click to Add.
29. In the Filter Configuration dialog box, in the Filter Type drop-down list box, click Limit, and then
click OK.
30. In the Properties pane, in the Default Value box, type 25, and then click Finish.
31. Click Save.
32. On the ribbon, click Create Lists & Form.
33. In the Create List and Form for Customer Contacts dialog, in the List name box, type Customer
Contacts, and then click OK.

35. On the Start screen, type Central Administration, and then press Enter.
37. On the list of service applications, click Business Data Connectivity Service.
38. On the list of external content types, on the Customer Contacts drop-down menu, click Set
Permissions.
40. Under Permissions for Everyone, select Execute and Selectable in Clients, and then click OK.
41. Browse to http://team.contoso.com.
42. If you are prompted for credentials, log on as CONTOSO\Administrator with password Pa$$w0rd.
43. On the Settings menu, click Site settings.
44. Under Site Actions, click Manage site features.
45. On the Site Features page, in the Offline Synchronization for External Lists row, click Activate.
46. On the Quick Launch navigation menu, click Customer Contacts.
47. On the ribbon, on the LIST tab, click Connect to Outlook.
48. In the Microsoft Office Customization Installer dialog box, click Install.
49. When the Microsoft Office Customization Installer dialog box reports that the customization was
successfully installed, click Close.
50. When the BCS has finished generating the installation package, Outlook will open automatically.
Point out the list of customer contacts.

Lab: Working with Business Data in Apps for SharePoint

Scenario
The IT team at Contoso wants to extend the asset-tracking solution you developed. The team would like
to be able to view a table of the asset tracking data, and filter it by class. To implement this functionality,
you will create an app and use the JavaScript object model to retrieve asset tracking data from the BCS.
You will then use jsRender, HTML 5, and CSS 3 to create a simple tabular representation of the data.
Objectives
In this lab, you will be able to:
 Use the JavaScript object model to interact with external content types.
 Use an app to present business data graphically.
Lab Setup

Exercise 1: Reading Business Data in Client-Side Code

Scenario
Contoso has an external content type named Product used in a site located at http://team.contoso.com.
Each product represents an asset in inventory. You need to create code to retrieve all products that are
older than three years and display the list on a page.
1. Start the OData Service
2. Create a SharePoint-Hosted App
3. Retrieve Asset Information by Using JSON
4. Display Asset Information in a Table

1. Open the ContosoODataService.sln solution from the E:\Labfiles\Starter\ContosoODataService
folder.
2. In the ContosoODataWebServcice.svc file, review the InitializeService method. Notice that this
method exposes the DimProducts, DimProductCategories, and DimProductSubcategories
entities. These map to the DimProduct, DimProductCategory, and DimProductSubcategory
database tables.
3. Start the solution without debugging. You should leave this service running, because you will use it in
the following tasks.

1. Create a SharePoint-Hosted app by using the following parameters:
o Name: AssetApp
o Locations: E:\Labfiles\Starter
2. Configure the new app to use http://dev.contoso.com for debugging, and to deploy the app as a
SharePoint-Hosted app.
3. Add an OData connection by using the following parameters:
o OData URL: http://localhost:12345/ContosoODataWebService.svc/
o Name: ContosoODataSource
4. Create an external content type for the following entities:
o DimProductSubcategories
o DimProducts
5. Create external lists for the content types.
 Task 3: Retrieve Asset Information by Using JSON

1. Open the Default.aspx page, and delete the existing HTML from the PlaceHolderMain content
control.
2. Add a button to the page. The button should:
a. Display the text Get Products.

b. Have an id value of cmdGetProducts.
Note: Use HTML to define the button. Do not use any server controls.
3. Beneath the button, add a div element with an id value of displayDiv.
4. Open the App.js file, and delete the contents of the file.
5. Define a function named onGetProducts. This function should:
a. Create a RESTful URL that retrieves all items from the DimProducts external list on the app web.
b. Use AJAX to send an HTTP GET request to the RESTful URL.
c. If the request is successful, call a function named onReturnData.
d. If the request fails, display the error message in a dialog box.
6. Define a function named onReturnData. This function should retrieve the results of the HTTP request
and store the results in a variable named oDataResult.
7. Bind the onGetProducts method to the click event of the cmdGetProducts button.
8. Add a breakpoint to the line that sets the value of oDataResult, and then start debugging.
9. When the page has finished loading, in Internet Explorer, click Get Products.
10. When the debugger reaches the breakpoint, in Visual Studio, press F10.
11. Hover over the text odataResult, and then on the context menu, expand odataResult.
12. Verify that the odataResult variable contains multiple sets of data, and then on the DEBUG menu,
click Stop Debugging.
13. Delete all breakpoints.
Note: Sample code for the App.js file is available in the E:\Labfiles\Starter\App01.txt file.
 Task 4: Display Asset Information in a Table

1. In Visual Studio, switch to the App.js file.
2. In the onReturnData function, define the markup for an HTML table with the following header
labels:
a. Product
b. Class
c. Brand
d. Unit Price
3. Iterate over the oDataResult variable. For each item in the oDataResult variable, construct an HTML
table row containing the following columns from the data source:
a. ProductName
b. ClassName
c. BrandName
d. UnitPrice
4. Append each row to the table you created, and then add the table to the displayDiv element.
5. Start debugging the app.
6. When the page loads, click Get Products. Verify that the app displays a table containing product
data.
Note: Sample code for the onReturnData function is available in the

E:\Labfiles\Starter\App02.txt file.
Results: After this exercise, you should have retrieved a list of products that are older than three years.
Exercise 2: Presenting Business Data in an App for SharePoint

Scenario
You need to filter the data being retrieved by class.
1. Filter Data by Class
2. Test the App
 Task 1: Filter Data by Class

1. In Visual Studio, switch to the Default.aspx file and locate the input element (near the bottom of the
page).
2. Immediately above the input element, add a select element with an id value of lstClass.
3. Add the following options to the select element:
a. An option with a value of 'Economy' (including the single quotation marks) that displays the text
Economy.
b. An option with a value of 'Regular' (including the single quotation marks) that displays the text
Regular.
c. An option with a value of 'Deluxe' (including the single quotation marks) that displays the text
Deluxe.
4. Switch to the App.js file.
5. In the onGetProducts function, add a line of code to the top of the function that retrieves the value
of the lstClass element.
6. Modify the line of code that constructs the RESTful URL to include an OData filter expression. The
expression should return only those items in which the value of ClassName column is equal to the
value of the lstClass element.
7. Save your work.
 Task 2: Test the App

1. Rebuild and deploy the solution, and then start debugging.
2. When the page has finished loading, click Get Products.
3. Notice that the page only displays items with a Class value of Economy.
4. In the drop-down list box, click Regular, and then click Get Products.
5. Notice that the page displays only items with a Class value of Regular.
6. In the drop-down list box, click Deluxe, and then click Get Products.
7. Notice that the page displays only items with a Class value of Deluxe.
Results: After this exercise, you should have filtered the data retrieved from the OData by class name.
Question: You need to access an external content type hosted in a SharePoint site from a
client Windows-based application. What object model should you use?
Question: You need to access an external content type hosted in a SharePoint site from a
SharePoint sandboxed solution. What object model should you use?
Question: You need to access an external list hosted in a SharePoint site from a SharePoint
app. What object model should you use?
Statement Answer
True or False: You can associate workflows

with external lists.
Test Your Knowledge

Question
What is the name of the process that manages the Business Connectivity Service Client Cache?
W3wp.exe
Mssearch.exe
BCSSync.exe
Noderunner.exe
Statement Answer
True or False: You can deploy an ECT via the

Client Side Object Model (CSOM)

In this module, you learned how external lists provide a familiar user experience to other SharePoint lists.
However, there are some missing features when compared with native list instances. You also learned how
to take advantage of your pre-existing business data in your native lists via business data columns to force
users to pick valid values.
You were exposed to four different APIs with which you can interact with external lists, and the
advantages and disadvantages of each. The preference is to utilize the CSOM and REST APIs via App for
SharePoint development.
Finally, you learned about the complex client-side runtime that allows applications to cache subscriptions
to data stored in external systems for use in Office client applications, thus putting data in the hands of
users via familiar Office applications.
12-1
Module 12
Managing and Accessing User Profile Data
Contents:
Lesson 1: User Profile Data in SharePoint 2013 12-2
Lesson 2: Options for Accessing User Profile Data 12-6
Lesson 3: Managing User Profile Data 12-9
Lab A: Accessing User Profile Data 12-15
Lesson 4: Managing User Profile Properties 12-20
Lab B: Managing User Profile Properties 12-25

Module Overview
User profiles enable you to access and collect a range of information about your users. You can use user
profile information to personalize your solutions for your users, and to make the solution more engaging
for your users. In this module, you will review key aspects of the user profile service and see how you can
write client-side and server-side code to access, update, and manage user profile properties.
Objectives
 Explain how user profile data is used in Microsoft® SharePoint® 2013.
 Describe the options and restrictions for accessing user profile data.
 Use client-side code and server-side code to access and update user profile data.
 Configure and manage user profile properties.

12-2 Managing and Accessing User Profile Data
Lesson 1
User Profile Data in SharePoint 2013
User profiles provide you with significant information about your users, but it is important to understand
the source of this information, the security implications of exposing the information, and how profile
properties are structured. In this lesson, you will learn about how profile properties are structured, the
data sources that SharePoint aggregates to produce a user profile, and the security risks that can be
introduced by exposing information in a user profile property. Finally, in this lesson you will learn about
the basic requirements to configure a development environment to develop user profile solutions.
Lesson Objectives
 Describe the high-level user profile architecture in SharePoint 2013.
 Describe the various data sources that SharePoint aggregates in user profiles.
 Explain the data security risks introduced by user profiles, and how to mitigate those risks.
 Describe the basic configuration requirements for a development environment that enables
developing solutions that utilize user profile data.
Introducing User Profiles

User profiles expand on the basic account
information stored for users of your SharePoint site.
With basic account information you can access a
user’s account name and sometimes a display
name. User profiles are provided by the User Profile
Service Application. You can access basic account
information without the User Profile Service
Application; however, if you need to integrate with
line-of-business applications or need to access
more than basic information, then you must use the
User Profile Service Application.
You can extend user profiles to store significantly

more information about your users. In addition to storing more information, you are also able to access
information from more data sources than is possible without user profiles. For example, with user profiles
you can access information stored in a line-of-business system and aggregate that information with
information stored in a directory service. When working with the data there is no difference in the
presentation of the data based on the source (although there is normally a restriction on how you can
update data based on the data source).
Profile Subtypes
In your organization, you may have many users who fit into different logical categories. You may need to
store different information about different categories of users. For example, for production staff you may
store only basic information, but for managers you may need to store additional information. You can
define profile subtypes to enable you to store different information about different types of users. Each
user is then added to a subtype. You can create profile subtypes by using the Central Administration web
site or by using code.
When you install the User Profile Service Application, SharePoint creates a default user subtype; by
default, all users are added to the default user subtype.
Property Data Sources

In SharePoint 2013, user profile properties can be
stored in a number of locations. Different locations
have different restrictions and considerations. The
storage locations fit into one three broad
categories:
 Directory services
 User (SharePoint)
 Business Connectivity Services
When you develop solutions that use user profiles

properties, it does not matter where the source
property is stored; you use the same syntax to
access all properties. The source of a profile property may dictate whether a property is read only or if you
can write to the property.
Directory Services
Profile information often comes from a directory service, for example Active Directory®. When you
configure a directory service, it may be read only or read/write. The implementation of SharePoint
integration with your directory service will determine the access you have to user profile properties from a
directory service.
User
Users can provide data that is stored in SharePoint databases. You can change properties where the value
provided by the user is stored in SharePoint without risk of the value being updated during
synchronization with a back-end system.
Business Connectivity Services

Business connectivity services enable you to access user profile information from line-of-business systems.
You may not be able to update profile information that has been retrieved from a line-of-business data
source, depending on the implementation.
Profile Properties and Data Protection

Most businesses store confidential information
about employees and other users in a directory
service or in line-of-business systems. It is possible
that you will also collect confidential information in
SharePoint. When you use user profiles to expose
information about a user, you should always be
aware of the implications for data protection. For
example, if you expose data stored in a line-of-
business system that is otherwise correctly secured
by using a BCS connector, you may expose
information to a wider audience than intended.
In SharePoint, you can specify privacy settings for

each user profile property. When you define a new user profile property, you can choose the default
privacy setting for that profile property. You can specify a policy that either enforces the privacy setting
for the profile property or gives users the option to override the default setting. In SharePoint 2013 there
are two options that you can use to define the privacy setting for a profile property, Public or Private.
When you specify the privacy setting in code, you must select a value from the Privacy enumeration. In
addition to the Public and Private privacy settings, the Privacy enumeration also includes Manager,
MyWorkgroup, and MyColleagues options. These are included for backwards compatibility and are
deprecated in SharePoint 2013; you should use only the Public and Private options in your solutions.
Additional Reading: You can set the default privacy setting for a user profile property by
using code. For more information on setting privacy settings on user profile properties, see How
to: Set Privacy Policies for User Profile Properties at
Demonstration: Reviewing the Default User Profile Properties

This demonstration shows you the default user profile properties and how the connection to Active
Directory is configured by using the Central Administration web site.
Demonstration Steps

3. Open the Central Administration web site.
4. Browse to the management page for the Contoso User Profile Service Application service
application.
5. Review the default properties.
6. View the properties of the First name property. Notice that this property is a single valued string
property with a maximum length of 250 characters. Review the default privacy settings for this
property.
7. Return to the management page for the Contoso User Profile Service service application.
8. Review the synchronization settings. Notice that the service application is configured for basic Active
Directory import, but that you can choose to use full SharePoint Profile Synchronization, or use an
external identity manager.
SharePoint Configuration Requirements and Considerations

You must configure the User Profile Service
Application to work with user profiles. The User
Profile Service Application enables you to manage
user profiles, profile properties, and other profile
properties. The User Profile Service Application is
preconfigured to work with either the User Profile
Service Windows® service or the User Profile
Synchronization Service Windows service. Both of
these services enable you to import user profile
information from Active Directory.
User Profile Service

With the User Profile Service Windows service you
can perform a basic import from Active Directory. The import is mono-directional; data is always pulled
from Active Directory and properties in SharePoint are overwritten. The ability to perform a basic import
from Active Directory is new in SharePoint 2013.
User Profile Synchronization Service

The User Profile Synchronization Service Windows service provides a more advanced synchronization
solution. With the User Profile Synchronization Service Windows service, you can synchronize properties in
both directions; however, each property can still be synchronized in only a single direction. For some
properties Active Directory will have precedence, while for others SharePoint will have precedence. It is
important that you know how profile information is synchronized before you make changes to profile
properties in your solutions. If you use two-way synchronization, you will need to use both the User
Profile Service, and the User Profile Synchronization Service.
The choice between the User Profile Service and User Profile Synchronization Service Windows service is
normally made during the design phase by SharePoint IT professionals, but it is important for developers
to understand the implication of the decision.
Lesson 2
Options for Accessing User Profile Data
Like most of the workloads in SharePoint 2013, development options have been extended significantly
when compared to earlier version of SharePoint. There is specific emphasis on providing client-side
options for developing solutions. This helps to make sure that solutions are compatible with SharePoint
Online®. However, there are still important considerations for choosing between client-side and server-
side code. In addition to choosing between development platforms, you will also need to learn how to
retrieve user profiles. While the options for retrieving a single user are straightforward, to retrieve multiple
users you can choose between enumerating users and searching for users. Your choice will normally
depend on the purpose of your solution.
In this lesson, you will learn about the development options and restriction in SharePoint 2013, as well as
see how to enumerate users, how to search for users, and why you might choose each of these options.
Lesson Objectives
 Describe the development options for managing user profile data.

 Write code to enumerate users.
 Develop solutions that use people search.
Development Options for Managing User Profile Data

The development options for developing solutions
that make use of user profile data have been
extended in SharePoint 2013. In addition, a number
of the existing APIs have been changed, with some
new properties and methods, and some properties
and methods being deprecated.
In SharePoint 2013, to interact with user profile

properties you can use the JavaScript object model
and REST, in addition to the .NET client- side object
model. This makes it easy to integrate user profiles
in apps. However, there is a big restriction on user
profile data: When you use the client-side APIs,
most of the user profile properties are read-only. The profile picture is the one exception to this rule. In
client-side code, you can use the PeopleManager.setMyProfilePicture method to update a profile
picture.
You can continue to user server-side code to manage user profile properties. In server-side code, you
have full read/write access to user profile properties.
Enumerating Users
In SharePoint 2013, you can enumerate users. You
can either enumerate users at a site level, or
enumerate users at the user profile service
application level.
Enumerating Users at the Site Level

When you enumerate users at the site level, the
collection of users that SharePoint returns is
restricted to those users who have access to the site.
When you enumerate users at the site level, you can
be sure that you retrieve every user who has access
to a site. However, you should be aware that some
site users may not have a user profile. You cannot
retrieve profile properties for users who do not have a user profile. You can enumerate site users in either
client-side or server-side code. To enumerate users at the site level, you iterate over the SPUser objects in
the AllUsers collection property of the SPWeb object that represents the site.
The following code example shows how to enumerate users at the site level by using server-side code:
Enumerating Site Users in Server-side Code

var users = SPContext.Current.Site.RootWeb.AllUsers;
foreach (var user in users)
{
}
Enumerating All Users with a User Profile

As an alternative to enumerating users at the site level, you can enumerate all users who have a user
profile by enumerating users against the user profile service application. When you enumerate users by
using the user profile service application you can be sure that all of the users will have a valid profile;
however, you cannot guarantee that you will enumerate all of the users for a given site, site collection, or
web application.
The following code example shows how to enumerate users at the user profile service application level by
using server-side code:
Enumerating User Profile Service Application Users in Server-side Code

var context = SPServiceContext.Current;
var userProfileManager = new UserProfileManager(context);
var users = userProfileManager.GetEnumerator();
while (users.MoveNext())
{
var user = users.Current;
}
While enumerating users can be appropriate if you need to update each user in a site or to make a
change to every user, often you will not need to perform an operation on every user. Enumerating users
often means processing user profile unnecessarily; you can use search to access only the required user
profiles.
Searching for Users

You can use SharePoint search to retrieve user
profile by using people search. Search can improve
the performance of your solutions by providing you
with a more refined set of users. You can perform
the same actions on users retrieved by using search
as you can with users that you enumerate from a
site, or from a user profile service application.
To search for a user, use standard keyword query

language. You specify the Local People Results
result source for people search.
Note: When you perform a search against a

result source, you must specify the ID of the result source. The ID of the Local People Results
result source is b09a7990-05ea-4af9-81ef-edfab16c4e31.
The following code example shows how to perform a people search by using the JavaScript client-side
object model:
People Search by Using the JavaScript Client-side Object Model

var queryText = "FirstName:" + firstName + " OR LastName:" + lastName;
var query = new Microsoft.SharePoint.Client.Search.Query.KeywordQuery(clientContext);
query.set_queryText(queryText);
query.set_sourceId("B09A7990-05EA-4AF9-81EF-EDFAB16C4E31");
clientContext.executeQueryAsync(function () {
$.each(results.m_value.ResultTables[0].ResultRows, function () {
var accountName = this.AccountName;
var preferredName = this.PreferredName;
}
}, function () {
alert("Error performing search.");
});
Note: Before you use people search, you must be certain that the search service is
configured correctly and is configured to crawl the My Sites web application. If the search service
does not crawl the My Sites site collection, people search will not function correctly.
Additional Reading: For more information on how to configure people search, see Deploy
people search in SharePoint Server 2013 at http://go.microsoft.com/fwlink/?LinkId=321954
Lesson 3
Managing User Profile Data
As part of a solution that uses user profile data, you will often need to retrieve user profile properties. You
may also need to update user profile properties. In this lesson, you will review the options for creating a
user profile, and how you can use both server-side and client-side code to retrieve user profile properties.
Finally, you will see how to use code to update profile properties.
Lesson Objectives
 Create a user profile for a user.
 Use client-side code to retrieve user profile properties.
 Use server-side code to retrieve user profile properties.
 Use server-side code to update user profile properties.
Creating User Profiles

In SharePoint 2013, developers, IT professionals,
and users can all create a user profile for a user.
When you work with user profiles, you should be
aware that a member of a site may not have a user
profile. You can create a user profile for a user by
using the CreateUserProfile method of the
UserProfileManager class.
When you work with user profiles by using server-

side code, you will need to add references to the
Microsoft.Office.Server and
Microsoft.Office.Server.UserProfiles assemblies.
You will also need to add a using statement for the
Microsoft.Office.Server.UserProfiles namespace in your application.
The following code example shows how to create a user profile for a user by using server-side code:
Creating a User Profile by Using Server-side Code

SPServiceContext serviceContext = SPServiceContext.GetContext(site);
UserProfileManager = new UserProfileManager(serviceContext);
UserProfile = userProfileManager.CreateUserProfile("CONTOSO\Mike");
Retrieving User Profile Properties by Using Client-side Code

When developing SharePoint solutions, you will
often want to display user profile properties by
using client-side code. SharePoint 2013 includes
extended APIs to enable you to work with user
profiles in client-side code. The JavaScript object
model is one of the client-side technologies that
you can use to interact with the user profile service.
When you work with the user profile service by
using the JavaScript Object Model, you will need to
register the SP.UserProfiles.js script file in your
page.
To retrieve user profile properties by using the

JavaScript Object Model, you must use the PeopleManager and GetUserPropertiesForUser classes from
the SP.UserProfiles namespace. Although you can use the JavaScript Object Model to retrieve user
profile properties, you cannot update the values of the properties from client-side code.
The following code example shows how to retrieve user properties by using client side code:
Retrieving User Properties with Client Side Code

// Obtain a reference to the current client context.
// Define an array or profile properties; only properties in this array will be

retrieved.
var properties = ["AccountName“, “FirstName“];
// Use a username to identify they user profile.

var username = "CONTOSO\Mike";
// Create a new instance of the PeopleManager class.

var peopleManager = new SP.UserProfiles.PeopleManager(clientContext);
// Create a UserProfilePropertiesForUser request

var profilePropertiesRequest = new SP.UserProfiles.UserProfileProeprtiesForUser
(clientContext, username, properties);
// Create a variable to store the properties by using the getUserPropertiesFor method of

the
// PeopleManage class instance.
var profileProperties =
peopleManager.getUserProfilePropertiesFor(profilePropertiesRequest);
// Load the request into the client context.

clientContext.load(profilePropertiesRequest);
// Execute the request in the client context.

clientContext.executeQueryAsync(function () {
// Process the results if the query returns successfully.
accountName = profileProperties[1];
}, function() {
// Handle the failure if the query does not return successfully.
});
Retrieving User Profile Properties by Using Server-side Code

You can also retrieve user profile properties by
using server-side code. You may want to use server-
side code if you develop a web part, a timer job, or
other server-side component. You will also need to
use server-side code to retrieve user profile
properties if you need to update user profile
property values.
To retrieve user profile properties, you must use the

UserProfile class. To simplify development, the
UserProfile class exposes properties that provide
easy access to common user profile properties, for
example the AccountName property.
For profile properties that the UserProfile class does not expose as a property (including custom
properties), you can use an indexer on the UserProfile instance to access the property. You must specify
the property name in the indexer. When you use the indexer to retrieve a property, you must then use the
Value property of the object returned by the indexer in order to retrieve the property value. For out-of-
the-box properties that are not exposed as properties of the UserProfile class, you can use the
PropertyConstants enumeration in the indexer; this reduces the risk of introducing a runtime exception,
and (by using Microsoft IntelliSense®) enables you to choose a property without the need to remember
(or look up) the exact property name. Obviously, the PropertyConstants enumeration does not include
the name of any custom properties you may create, so for custom properties you must use a string with
the indexer.
Some properties contain multiple values. For these properties, you must use a slightly different technique
to obtain the value of the property. You can choose to either enumerate each of the values stored in the
property (by using the GetEnumerator method), or you can use an indexer to access each value.
The following code example shows how to retrieve user profile values for a given user by using server-side
code:
Retrieving User Profile Properties by Using Server-side Code

// Obtain the reference to the UserProfileManager class for the current service context.
UserProfileManager userProfileManager = new UserProfileManager(SPServiceContext.Current);
// Obtain a reference to the user profile for the current user (if the current user does
not already have
// a profile, create one).
UserProfile user = userProfileManager.GetUserProfile(true) ;
// Properties for common profile properties.

var accountName = user.AccountName;
// Indexer for any properties.

var accountName = user["AccountName"].Value;
// PropertyConstants enumeration to simplify development.

var accountName = user[PropertyConstants.AccountName].Value;
// Enumerator or index for multi-value profile properties.

var values = user[PropertyConstants.AccountName].GetEnumerator();
var value1 = user[PropertyConstants.AccountName][0];
Note: The UserProfileManager class exposes a GetUserProfile method that you can use
to obtain a single user profile. You can use this method to retrieve the user profile of the current
user, or you can use this method to retrieve the user profile of a different user by providing the
user name. This method will also create a user profile, if necessary.
Demonstration: Retrieving User Profile Properties in Server-side Code

This demonstration shows you how to obtain a reference to the user profile service application in C#
server-side code. It also shows how to enumerate the properties for the default profile subtype.
Demonstration Steps
4. In Microsoft Visual Studio®, on the FILE menu, point to Open, and then click Project/Solution.
5. In the Open Project dialog box, browse to E:\Democode\ManageUserProfileProperties, click

ManageUserProfileProperties.sln, and then click Open.
6. In Solution Explorer, expand ManageUserProfileProperties, and then double-click Program.cs.
7. The code in this class obtains a reference to the user profile service application, and then enumerates
the properties of the default profile subtype.
8. In Solution Explorer, right-click ManageUserProfileProperties, point to Debug, and then click Start
new instance.
9. Visual Studio will display a UserProfileApplicationNotAvailableException exception because the

Administrator user (the current user) does not have permission to connect to the user profile service
application.
10. On the DEBUG menu, click Stop Debugging.
11. In Solution Explorer, expand Loader, and then under Loader, double-click Program.cs.
12. Review the code. To connect to the user profile service application, the account requires specific
permissions. The Administrator account does not have these permissions, but the SPFarm account
does. This code grants the SPFarm account the necessary permissions to run an interactive
application (by adding the account to the Domain Admins security group) before starting the
ManageUserProfileProperties application in the context of the SPFarm account. This enables the
application to connect to the user profile service application. Finally, the code removes the SPFarm
account from the Domain Admins security group.
13. Set the Loader project as the Startup project.

14. On the DEBUG menu, click Start Debugging. In the console window, point out the list of profile
properties.

Updating User Profile Properties

You can develop solutions that enable users to
update user profile properties by using server-side
code. You must use the UserProfile class to update
the profile properties.
You must use one of the following techniques to

update the property value:
 For single-valued profile properties that the
UserProfile class exposes as a property, assign
the new value to the property.
 For single-valued profile properties that you
access by using an indexer, assign the new
value to the Value property of the object.
 For multi-valued profile properties, use the Add method to add a new value, or use index notation to
update an existing value.
After you update the value or add a new value to a multi-valued property, you must call the Commit
method of the UserProfile class to save the changes to the database.
The following code example shows how to update user profile property values by using server-side code:
Updating User Profile Properties by Using Server-side Code

UserProfile user = … ; // Assume a valid UserProfile instance.
// Common profile properties.

userProfile.DisplayName = "Display Name";
// Any profile property.

userProfile["FirstName"].Value = "First Name"
// Multi-valued properties.
userProfile[PropertyConstants.Skills].Add("SharePoint Development");
userProfile[PropertyConstants.Skills][0] = "Web Development";
// Persist changes.
userProfile.Commit();
Note: SharePoint does not permit you to update a user profile property during a page GET
request. You can override this by setting the AllowUnsafeUpdates property of the SPWeb class
to true.
While generally you cannot use client-side code to update a user profile property, the profile picture is an
exception to this rule. You can update a user's profile picture by using the setMyProfilePicture method
exposed by the PeopleManager class in client-side code.
Additional Reading: For more information on working with user profiles in SharePoint
2013, see Work with user profiles in SharePoint 2013 at
Discussion: Accessing User Profile Data with Client-side Code

The instructor will now lead a brief discussion of
when it is appropriate to access user profile
properties by using client-side code.
Lab A: Accessing User Profile Data

Scenario
The human resources team needs to view user profiles for company employees. They must be able to
locate an employee profile quickly by searching for the employee. They must be able to search for users
by account name, name, or by specifying the user's department. Your task is to add functionality to an
app to provide the search functionality by using client-side code.
Objectives
 Add search functionality to an app for SharePoint.
 Retrieve user profile properties by using client-side code.
Lab Setup

Exercise 1: Add People Search Functionality to an App

Scenario
In this exercise, you will add people search functionality to an app. You will add controls to the app, and
then you will add JavaScript to search for users based on search criteria entered by the user. Finally, you
will test the app by searching for users by account name, name, and department. You will combine the
criteria to refine search results.
1. Review the starter solution
2. Add Controls to Enable Users to Enter Search Criteria
3. Add code to search for users.
4. Test the App
 Task 1: Review the starter solution

1. Use Visual Studio to open the ContosoUserProfileApp solution from the E:\Labfiles\Starter\ CUPA
folder.
2. Review the markup in the Default.aspx file. Notice that the file contains a div element with the id
search, and a div element with the id results.
 Task 2: Add Controls to Enable Users to Enter Search Criteria

1. Add markup to the div with the id search to define a paragraph that contains a label with the text
Account Name, and a text box with the id text.
Name, and a text box with the id name.
Department, and a text box with the id department.
4. Add markup to the div with the id search to define a paragraph that contains a button with the text
Search, and a text box with the id submitSearch.
5. Add markup to the div with the id results to define a paragraph that contains an anchor tag with the
text New Search. When the user clicks the anchor tag, the browser should invoke the
Contoso.UserProfileApp.showSearch function.
6. Add markup to the div with the id results to define a div tag with the id users.
7. Review the markup in the App.css file. Notice that the markup defines the layout for the elements
you have added in this task
 Task 3: Add code to search for users.

1. In the Default.aspx file, add a script tag to reference the /_layouts/15/sp.search.js file.
2. Add a function to the Contoso.UserProfileApp function named searchUsers. The searchUsers

function should perform the following tasks:
a. Clear any existing results by setting the inner HTML of the users div to an empty string.
b. Construct a query string by using the values from the accountName, name and department
text boxes. The query string should contain only properties where a value has been provided by
the user, and should include the following property mappings:
Text box Managed property
accountName AccountName
name FirstName OR LastName OR PreferredName
department Department
c. Create a new instance of the Microsoft.SharePoint.Client.Search.Query.KeywordQuery class

named query by using the current context as a parameter.
d. Set the queryText property of the query object to the query string you constructed.
e. Set the sourceId property of the query object to B09A7990-05EA-4AF9-81EF-EDFAB16C4E31

(this is the ID of the People Results result source).
f. Create a new instance of the Microsoft.SharePoint.Client.Search.Query.SearchExecutor class

named searchExecutor by using the current context as a parameter.
g. Define a new variable named results and initialize it to the result of invoking the executeQuery
method of the searchExecutor class by using the query object as a parameter.
h. Use the current client context to execute the query asynchronously.
i. If the query returns successfully, hide the search div and show the results div.
j. If the query returns successfully, reset the values of the accountName, name, and department
text boxes.
k. If the query returns successfully, but the result set does not contain any users, display the
message No users for your search criteria. in the users div.
l. If the query returns successfully, and the result set does contain users, append an h1 tag with the
text Users to the users div.
m. If the query returns successfully, and the result set does contain users, for each user, append a div
element to the users div. The div element should contain an anchor element with the following
properties:
Property Value
onclick attribute Contoso.UserProfileApp.displayProfile(this)
data-username attribute The AccountName property of the search result
Text The PreferredName property of the search result
n. If the query does not return successfully, displays an alert message with the text Error
performing search.
3. Add code to the return statement of the Contoso.UserProfileApp function to expose the
searchUsers method.
4. Add code to add the searchUsers method as the click event handler for the submitSearch button
when the page is ready.

1. Start debugging.
2. On the User Profile Search page, in the Account Name box, type Administrator, and then click
Search.
3. Verify that a single user is returned with the display name Administrator.
4. Click New search.
5. In the Name box type Smith, and then click Search.
6. Verify that two results are returned.

8. In the Department box, type Marketing, and then click Search.
9. Verify that SharePoint returns approximately 50 users.
11. In the Name box, type Smith, in the Department box type Marketing, and then click Search.
12. Verify that a single user is returned with the display name Denise Smith.
Results: After completing this exercise, you should have added search functionality to an app.
Exercise 2: Display User Properties in the App

Scenario
In this exercise, you will modify an app to retrieve a selection of user profile properties for a specified user,
and then you will add code to display those properties. Finally, you will test the app.
1. Add code to retrieve user profile properties
2. Test the App
 Task 1: Add code to retrieve user profile properties

1. In the Default.aspx file, add a script tag to reference the /_layouts/15/sp.userprofiles.js file.
2. Add a function to the Contoso.UserProfileApp function named displayProfile. The displayProfile

function should accept a single parameter named link and perform the following tasks:
a. Create a new array named requiredProperties that contains the following values:
i. AccountName
ii. FirstName
iii. LastName
iv. PreferredName
v. Department
vi. Company
b. Retrieve the username of the required profile by using the value of the data-username attribute
of the link passed as a parameter to the function. Store the username in a new variable named
username.
c. Create a new instance of the SP.UserProfiles.PeopleManager class named peopleManager by

using the current context as a parameter.
d. Create a new instance of the SP.UserProfile.UserProfilePropertiesForUser class named

profilePropertiesRequest by using the current context, the username variable, and the
requiredProperties array as parameters.
e. Invoke the getUserProfilePropertiesFor method of the peopleManager object by using the

profilePropertiesRequest object as a parameter.
f. Use the current client context to load and execute the profilePropertiesRequest query.
g. If the query returns successfully, display the results in the profile div. Display each property on a
new line, and label each property.
h. If the query does not return successfully, display an alert message with the text Error retrieving
user profile.
3. Add code to the return statement of the Contoso.UserProfileApp function to expose the
displayProfile method.
4. Modify the searchUsers function to clear any existing profile data from the profile div by setting the
inner HTML to an empty string; you should perform this step immediately after the code that clears
the users div.
5. Modify the searchUsers function to render each search result as a link. When a user clicks the link,
the browser should invoke the Contoso.UserProfileApp.displayProfile method, and pass itself as a
parameter.

1. Start debugging.
2. On the User Profile Search page, in the Name box, type Smith, and then click Search.
3. Click Denise Smith.
4. Verify that the app displays the profile information for Denise Smith.
Results: After completing this exercise, you should have modified an app to retrieve a user profile.
Lesson 4
Managing User Profile Properties
In addition to working with existing user profile properties, you may need to create new user profile
properties or update an existing user profile property, for example, by changing the default privacy
setting for the property. In this lesson, you will learn how to manage user profile properties, and how to
create new user subtypes.
Lesson Objectives
 Create user subtypes.
 Add user profile properties.
 Update user profile properties.
 Delete user profile properties.
Managing User Profile Subtypes

Subtypes enable you to define different properties
for different categories of user. When you define a
new profile property, you can choose to add it to
one or more profile subtypes. For each profile
subtype to which you add a property, you can
customize the profile property. For example, you
can define a different default privacy level for the
same property in different subtypes.
You can use code to manage user sub types. To

manage user profile subtypes, you must use an
instance of the ProfileSubtypeManager class. You
can obtain a reference to the
ProfileSubtypeManager class by using the static Get method of the class. The ProfileSubtypeManager
class exposes the following methods which enable you to manage user profile subtypes:
 CreateSubtype. The CreateSubtype method enables you to create a new subtype. When you create a
new subtype, you must specify a profile type. The profiles types are defined in the ProfileType
enumeration. You must specify the ProfileType.User value in order to create a new user profile
subtype.
 DeleteSubtype. The DeleteSubtype method enables you to delete an existing subtype. You must
specify the name of the subtype as a parameter.
 GetProfileSubtype. The GetProfileSubtype enables you to retrieve a reference to a profile subtype by

specifying the name of the subtype as a parameter.
 GetSubtypesForProfileType. The GetSubtypesForProfileType method enables you to retrieve a

collection of profile subtypes by specifying a type of profile as the parameter. To retrieve user profile
subtypes, specify the ProfileType.User value.
The following code example shows how to use the ProfielSubtypeManager class to manage user profile
subtypes:
Managing User Profile Subtypes

// Obtain a reference to the current service context.
SPServiceContext serviceContext = SPServiceContext.Current;
// Obtain a reference to the profile subtype manager.

ProfileSubtypeManager subTypeManager = ProfileSubtypeManager.Get(serviceContext);
// Create a new profile subtype.

ProfileSubtype newSubtype = subtypeManager.CreateSubtype("Name", "Display name",
ProfileType.User);
// Delete a profile subtype.

subtypeManager.DeleteSubtype("Name");
// Retrieve a profile subtype by specifying the subtype name.

ProfileSubType subtype = subtypeManager.GetProfileSubtype("Name");
// Retrieve a collection of profile subtypes for a type of profile.

List<ProfileSubtype> profiles =
(List<ProfileSubtype>)subtypeManager.GetSubtypesForProfileType(ProfileType.User);
Note: If you have a valid instance of the ProfilePropertyManager class defined in your
code, you must call the Reset method of the ProfilePropertyManager class to invalidate the in-
memory cache before you use a new profile subtype in your code.
Adding User Profile Properties

You can add new properties to user profiles. A
profile property consists of three components: a
core property, a type property, and a subtype
property. These three components form a hierarchy;
you can use one core property to create one or
more type properties, which in turn you can use to
create one or more subtype properties.
A core property defines the name of the property
and basic information about the property. A core
property is not mapped to a type of profile or a
user subtype. A type property defines additional
properties about the property. You can create a
type property based on a core property for each profile type (user, group, or organization). Finally, a
subtype property links a type property with a profile subtype, and defines additional fields.
To create profile properties, you must use manager classes for each type of property. You obtain
references to the manager classes by using the ProfilePropertyManager property of the
UserProfileConfigManager class.
The following code example shows how to define a user profile property:
Creating User Profile Properties

// Obtain a reference to the ProfilePropertyManager class.
ProfilePropertyManager propManager =
new UserProfileConfigManager(SPServiceContext.Current).ProfilePropertyManager;
// Obtain a reference to the CorePropertyManager class by using the GetCoreProperties

method of the
// ProfilePropertyManager class.
CorePropertyManager corePropManager = propManager.GetCoreProperties();
// Create a new core property by using the Create method of the CorePropertyManager
class.
// Specify false to indicate the core property is a property not a section.
CoreProperty coreProp = corePropManager.Create(false);
// Set properties of the new core property.

coreProp.Name = "Name";
coreProp.Displayname = "Display Name";
coreProp.Type = PropertyDataType.StringSingleValue;
coreProp.Length = 50;
// Call the Commit method to save the changes to the database.

coreProp.Commit();
// Obtain a reference to the ProfileTypePropertyManager class by using the

GetProfileTypeProperties
// method of the ProfilePropertyManager class.
// Specify ProfileType.User to indicate that this is a user profile property.
ProfileTypePropertyManager typePropManager =
propManager.GetProfileTypeProperties(ProfileType.User);
// Create a new type property by using the Create method of the

ProfileTypePropertyManager class.
// Specify the core property on which this type property is based as the parameter.
ProfileTypeProperty typeProp = typePropManager.Create(coreProp);
// Set the properties of the type property.

typeProp.IsVisibleOnViewer = true;
// Call the Commit method to save changes to the database.

typeProp.Commit();
// Obtain a reference to the ProfileSubtypePropertyManager class by using the

GetSubtypeProperties
// method of the ProfilePropertyManager class.
// Specify the name of the user subtype as the parameter.
ProfileSubtypePropertyManager subtypePropManager =
propManager.GetSubtypeProperties("Subtype Name");
// Create a new subtype property by using the Create method of the

ProfileSubtypePropertyManager class.
// Specify the type property on which this subtype property is based as the parameter.
ProfileSubtypeProperty subtypeProp = subtypePropManager.Create(typeProp);
// Set the properties of the subtype property.

subtypeProp.IsUserEditable = true;
subtypeProp.DefaultPrivacy = Privacy.Public;
subtypeProp.UserOverridePrivacy = true;
// Call the Commit method to save the changes to the database.

subtypeProp.Commit();
Note: To manage user profile properties requires permissions on the User Profile Service
Application. The permissions must be granted to the account under which the code is running;
for example, the current user, the web application service account, or another service account.
Updating User Profile Properties

You can update an existing property for a given
profile subtype by using an instance of the
ProfileSubtypePropertyManager class to obtain a
reference to the profile property. After you obtain a
reference to the property you can make your
changes. After you have made your changes you
must use the Commit method exposed by the
property instance.
The following code example shows how to update

profile properties for the default profile subtype.
Updating Profile Properties

SPServiceContext context = SPServiceContext.Current;
// Obtain a reference to the UserProfileManager instance.
UserProfileManager uPM = new UserProfileManager(context);
// Obtain a reference to the ProfileSubtypePropertyManager instance that represents the
default profile subtype.
ProfileSubtypePropertyManager defaultPSPM =
upm.DefaultProfileSubtypeProperties;
// Obtain a reference to the property.
ProfileSubtypeProperty property =
defaultPSPM.GetPropertyByName(propertyName);
// Update the property.
// Call the Commit method to persist the changes to the property
property.Commit();
Deleting User Profile Properties

You can delete user profile properties by using the
profile property manager classes
(CorePropertyManager,
ProfileTypePropertyManager, and
ProfileSubtypePropertyManager). Each profile
property manager class exposes a
RemovePropertyByName method. You must
specify the name of the property as a parameter.
When you delete a property, SharePoint will

remove any properties that are based on that
property. For example, if you delete a core
property, SharePoint will also remove any type
properties and in turn subtype properties that are based on the core property. If you delete a property,
SharePoint will also delete any properties that are less specific, if the property that you are removing is the
only property that is based on the less specific property. For example, if you delete a type property,
SharePoint will also delete the core property if the property that you are deleting is the only property that
is based on the core property.
After you delete a property, you should always call the Reset method of the ProfilePropertyManager
instance to invalidate the in-memory cache of properties. If you do not invalidate the in-memory cache,
your code may not work as expected.
The following code example shows how to delete profile properties:
Deleting Profile Properties

// Obtain a reference to the ProfilePropertyManager class.
ProfilePropertyManager propManager =
new UserProfileConfigManager(SPServiceContext.Current).ProfilePropertyManager;
// Obtain a reference to the ProfileSubtypePropertyManager class, for a named subtype.

ProfileSubtypePropertyManager subtypePropManager =
propManager.GetSubtypeProperties("Subtype Name");
// Remove a subtype property.

subtypePropManager.RemovePropertyByName("Name");
// Reset the in memory cache.

propManager.Reset();
// Obtain a reference to the ProfileTypePropertyManager class for User profiles.

ProfileTypePropertyManager typePropManager =
propManager.GetProfileTypeProperties(ProfileType.User);
// Remove a type property.

typePropManager.RemovePropertyByName("Name");
// Reset the in memory cache.

propManager.Reset();
// Obtain a reference to the CorePropertyManager class.

CorePropertyManager corePropManager = propManager.GetCoreProperties();
// Remove a core property.

corePropManager.RemovePropertyByName("Name");
Additional Reading: For more information on working with user profiles in server-side
code, see How to: Work with user profiles and organization profiles by using the server object
model in SharePoint 2013 at http://go.microsoft.com/fwlink/?LinkId=321952
Lab B: Managing User Profile Properties

Scenario
The human resources team needs to add and remove user profile properties in response to business
needs; for example, to enable them to track compliance with regulations, and to track security clearances
for specific projects. As regulations change or projects finish, they will remove the profile property to
avoid a proliferation of properties. In addition to the ability to add and remove properties, they need to
be able to control visibility of the properties. Your task is to add code to a web part to display, update,
add, and delete user profile properties.
Objectives
 Enumerate profile properties by using server-side code in a web part.
 Manage user profile properties with server-side code.
Lab Setup
Exercise 1: Add Code to Display User Profile Properties

Scenario
In this exercise, you will add code to a web part to display user profile properties. You will include code to
manage those properties. You will implement the event handlers for the controls in the next exercise. You
will also grant permissions to enable the code to run correctly. Finally, you will test the web part.
1. Grant the Domain Admins Account Administrative Permissions on the User Profile Service Application
2. Add Code to Display User Profile Properties
3. Test the Web Part
 Task 1: Grant the Domain Admins Account Administrative Permissions on the User
Profile Service Application
1. Open the Central Administration web site.
2. Browse to the Manage Service Applications page.
3. Grant the Domain Admins Active Directory security group the Manage Profiles permission on the
Contoso User Profile Service Application service application.

 Task 2: Add Code to Display User Profile Properties

1. Use Visual Studio to open the ContosoManagePropertiesWebPart solution from the
E:\Labfiles\Starter\CMPWP folder.
2. Review the ContosoManagePropertiesWebPart.ascx file. Notice that the file defines a text box, two
buttons and a table.
3. Add project references to the Microsoft.Office.Server and Microsoft.Office.Server.UserProfiles

assemblies.
4. Add a using statement for the Microsoft.Office.Server.UserProfiles namespace.
5. In the ContosoManagePropertiesWebPart class, add a new private method named

LoadProperties. The method should not return a value.
6. Add code to the LoadProperties method to perform the following tasks:
a. Clear the rows collection of the propertiesTable.

b. Create a new instances of the UserProfileManager class by using the current service context as a
parameter.
c. Invoke the Reset method of the DefaultProfileSubtypeProperties property of the

UserProfileManager instance.
d. Define an IEnumerator<ProfileSubtypeProperty> object named properties by using the

GetEnumerator method of the DefaultProfileSubtypeProperties property of the
UserProfileManager instance.
e. Iterate through each property in the properties enumerator. For each property perform the
following tasks:
i. Verify that the property is a property; if the property is a section, skips the property.
ii. Define a new TableRow.
iii. Add a cell to the row. Set the Text property of the cell to the Name property of the current
profile property.
iv. Add another cell to the row. The cell should contain a drop down list with the values Private
and Public as options.
v. Set the selected item in the drop down list based on the default privacy setting of the current
property.
vi. Add an attribute to the drop down list named data-propertyName, with the value set to the
Name property of the current property.
vii. Set the ID property of the drop down list to the concatenation of UserProfileProperty-
PrivacySetting- with the Name property of the current property.
viii. Specify an event handler for the drop down list’s SelectedIndexChanged event named
privacyOptions_SelectedIndexChanged (you will implement this method in the next
exercise).
ix. Add another cell to the row. The cell should contain a button with the text Delete.
x. Add an attribute to the button named data-propertyName, with the value set to the Name
property of the current property.
xi. Set the ID property of the button to the concatenation of UserProfileProperty-

DeleteButton- with the Name property of the current property.
xii. Specify an event handler for the button’s Click event named deleteButton_Click (you will
implement this method later in the next exercise).
xiii. Add the row to the Rows collection property of the propertiesTable table.
7. Add code to the OnInit method to invoke the LoadProperties method.
8. Add a new private method named privacyOptions_SelectedIndexChanged to the class. The

method should take two parameters, an object named sender, and an EventArgs named e. You will
implement this method in the next exercise. The method should not return anything.
9. Add a new private method named addProperty_Click to the class. The method should take two
parameters, an object named sender, and an EventArgs named e. You will implement this method
in the next exercise. The method should not return anything.
10. Add a new private method named deleteButton_Click to the class. The method should take two
parameters, an object named sender, and an EventArgs named e. You will implement this method
in the next exercise. The method should not return anything.
 Task 3: Test the Web Part

1. Start the solution with debugging enabled.
Note: If the solution fails with a UserProfileApplicationNotAvailableException

exception, you should stop, and then restart debugging. This exception occurs when your code
starts to execute before the User Profile Application has restarted after IIS is reset by Visual Studio
during the solution deployment process.
2. Add the ContosoManagePropertiesWebPart web part to the Contoso Development Site home
page.
3. Verify that the ContosoManagePropertiesWebPart displays a list of properties and a corresponding

privacy setting and Delete button for each property.
Results: After completing this exercise, you should have added code to display user profile properties on
a web part.
Exercise 2: Add Code to Manage User Profile Properties

Scenario
In this exercise, you will modify the web part to manage user profile properties. You will add code to
enable a user to add a new property, you will add code to delete a property, and then you will add code
to update an existing property. Finally, you will test the web part.
1. Add Code to Create a New User Profile Property

2. Add Code to Delete a User Profile Property
3. Add Code to Update a User Profile Property
4. Test the Web Part

 Task 1: Add Code to Create a New User Profile Property

1. Add code to the addProperty_Click method to create a new user profile property. You should use
the value of the namePropText text box as the name of the property. You should create a core
property, type property and profile subtype property for the default user profile subtype. The
property should have the following properties:
Property Value
Data type single string
Data length 50
IsVisibleOnViewer true
IsUserEditable true
Default privacy public
UserOverridePrivacy true
2. Add code to the addProperty_Click method to invoke the LoadProperties method.
 Task 2: Add Code to Delete a User Profile Property

1. Add code to the deleteButton_Click to delete the selected subtype property. You should use the
data-propertyName attribute of the button to identify the user profile property to delete, and you
should check that the property exists before you remove it.
2. Add code to the deleteButton_Click method to invoke the LoadProperties method.
 Task 3: Add Code to Update a User Profile Property

1. Add code to the privacyOptions_SelectedIndexChanged method to perform the following actions:
a. Retrieve the selected property by using the data-propertyName attribute of the drop-down list
control to identify the user profile property.
b. Update the DefaultPrivacy property of the user profile property based on the selected value of
the drop-down list.
c. Save the changes to the database.
2. Add code to the privacyOptions_SelectedIndexChanged method to invoke the LoadProperties

method.

1. Start the solution with debugging enabled.

2. Add a new property with the name New Property. After you click Add Property, the page may take
some time to update. Wait for the page to update before you continue. Do not click Add Property
twice, or the code may throw an exception.
3. Change the default privacy for the New Property property to Private.
4. Delete the New Property property.
5. Close Internet Explorer
Results: After completing this exercise, you should have updated a web part to include functionality to
manage user profile properties.

In this module, you saw how user profiles can provide you with extensive information about your users.
You learned how you can use people search to retrieve user profiles or to enumerate users at a site or user
profile service application level. You then looked at how to use server-side and client-side code to
manage user profiles. Finally, you looked at how you can manage profile properties by using server-side
code.
Review Question(s)
Statement Answer
True or False: User profile properties from a

line-of-business application exposed by using
the User Profile Service Application do not
increase the risk of exposing confidential
information.
Statement Answer
True or False: All site users have a user profile.
Test Your Knowledge

Question
Which of the following statements is true?
You can update all user profile properties by using either server-side or client-side code.
You can update all user profile properties by using server-side code only.
You can update all user profile properties by using client-side code only.
You can update all user profile properties by using server-side code, and the user profile
picture by using client-side code.
You can update all user profile properties by using client-side code, and the user profile
picture by using server-side code.
Statement Answer
True or False: You can create more than one

subtype property based on a single type
property.
13-1
Module 13
Customizing the Social Workload
Contents:
Lesson 1: Overview of the Social Workload 13-2
Lesson 2: Developing Social Solutions 13-5
Lesson 3: Working with Feeds 13-15
Lab: Creating a Social App Part 13-23
Module Overview
Enterprises of all sizes are integrating social solutions into their workplaces. With proper use, social
solutions can help to improve productivity, encourage innovation, and increase morale. Microsoft®
SharePoint® 2013 includes many social features that are either new or have been significantly updated. In
this module, you will see some of the social features in SharePoint 2013, and you will see how you can
develop apps that extend and customize the social workload, tailoring the experience for your business
needs.
Objectives
 Describe the main components of the social workload.
 Develop solutions to extend the social workload.
 Create solutions that make use of the newsfeed functionality in SharePoint Server 2013.
13-2 Customizing the Social Workload
Lesson 1
Overview of the Social Workload
In this lesson you will review the social workload in SharePoint 2013. You will consider some of the
changes from the social features in the previous versions of SharePoint, and you will learn about how to
configure a development environment to support social solutions.
Lesson Objectives
 Describe the key components of the social workload in SharePoint 2013.
 Explain the major changes made to My Sites in SharePoint 2013.

 Configure a development environment for Social Solutions
Introducing the Social Workload

SharePoint 2013 includes a number of social
features that enable users to collaborate with
content and with each other. Features such as the
ability to follow content and users, like content and
users, and post to newsfeeds associated with a
user’s My Site or project site. Many of these features
will feel very familiar to users of existing social
network sites.
The user’s My Site is the center of most of the social

features in SharePoint 2013, although community
sites that provide forums also form an important
part of the social experience. To create a
community site, you create a site by using the appropriate site template. You can manipulate community
sites by using site and list manipulation techniques.
Changes to My Sites in SharePoint 2013

In SharePoint 2010 and earlier versions of
SharePoint, users could create a personal site
known as a My Site. On their My Site they could
add documents, and add or amend profile
information. A user would specifically visit their My
Site to use the social features of SharePoint.
In SharePoint 2013, the user’s My Site is still hosted

in a private site collection, typically in a different
web application; however, the social features are
more integrated throughout SharePoint. The
personal site is now broken down into three distinct
hubs: Newsfeed, SkyDrive, and Sites. In addition to
interacting with the social features by using the three main hubs, users can also interact through other
sites. For example, by default, sites have a follow button. Users can click the follow button and the site will
then appear in their list of followed sites. Similarly, sites can have newsfeeds. From a newsfeed, users can
follow other users, hashtags, or other social entities. The user’s interactions are reflected throughout
SharePoint; for example, if you are following a user you will get options to stop following that user instead
of options to follow them. The following data is still stored in the My Site.
The three main hubs of the user’s My Site can now be accessed directly from most SharePoint pages. This
ensures that a user does not need to navigate to a My Site landing page and then to a specific page on
their My Site; the access is much more direct.
The newsfeed hub provides access to a user’s feed, where they can post updates similar to posting on
other social networks. For the newsfeed hub, users can also view profile information and edit their own
profile information. In addition, the newsfeed hub provides access to the user’s blog, task list, and other
apps that the user has added.
The SkyDrive hub provides access to documents that the user has stored in the cloud. The files stored in
the cloud can be synchronized with a Windows PC, so users can simply edit the file locally and the
changes will be mirrored to the SkyDrive document store. The SkyDrive hub (also known as SkyDrive Pro)
provides functionality similar to Microsoft SkyDrive, but with the files being stored on a user’s My Site
instead of in SkyDrive cloud storage. Files added to the SkyDrive hub can easily be shared with other users
within the organization.
The Sites hub enables the user to manage their followed sites. In addition, the user can see suggested sites
(users can suggest sites to other users). Also, users can use the Sites hub to create new sites if they have
the necessary permissions.
Demonstration: Using My Sites in SharePoint 2013

This demonstration shows you the new My Site interface, each of the three social hubs, and an overview
of some of the social features in SharePoint 2013.
Demonstration Steps
3. On the Start screen, click Internet Explorer.
4. In Internet Explorer, in the address bar, type http://my.contoso.com, and then press Enter.
5. If SharePoint displays the We’re still collecting the latest news. You may see more if you try
again a little later message, periodically refresh the page. This may take many minutes. Explain that
SharePoint uses timer jobs to populate the newsfeed and that as a result of the virtual machine being
shut down for extended periods, these timer jobs must execute before the feed is populated. This is
unlikely to happen in a production environment.
6. Point out the Newsfeed page including the Following, Everyone, and Mentions feeds.
7. On the Quick Launch menu, click About me.
8. Point out the feed of activities.
9. On the Quick Launch menu, click Blog.
10. Point out the blog entries and blog tools.
11. In Internet Explorer, click Back to Administrator.
12. On the Quick Launch menu, click Apps.

13. Point out the list of apps, and the option to add an app.
14. On the Quick Launch menu, click Tasks.
15. Point out the list of tasks.
16. On the SharePoint menu bar, click SkyDrive.
17. Point out the list of documents, and on the Quick Launch menu, point out the Followed Documents
link.
18. On the SharePoint menu bar, click Sites.
19. Point out the list of sites currently being followed.
Configuring a Development Environment for Social Solutions

To develop social solutions, you must first configure
your development environment. Social solutions
rely on a number of service applications and
services to function correctly. To support all of the
social features, you should deploy the following
service applications:
 State Service
 Managed Metadata Service
 Search Service Application
 User Profile Service Application
In addition to the service applications, there are a number of services that must be running for social
features to work correctly. You should confirm that the following services are running.
 Distributed Cache
 Managed Metadata Web Service
 Search Host Controller Service
 Search Query and Site Settings Service
 SharePoint Server Search
 User Profile Service (optional)
 User Profile Synchronization Service (optional)
 Work Management Service
Social solutions often use search. To simplify your development, you should confirm that the search
service has permissions to access all of the site collections and web applications in your environment,
including the web application that is hosting My Site sites. You should also consider configuring the
content source to continuously crawl content. This can help to ensure that new items appear in search
results promptly, and without running a manual search crawl each time. You should be aware that despite
a crawl running all of the time, there will normally still be a delay between when a new item is added to
SharePoint and when that item appears in search results.
Lesson 2
Developing Social Solutions
In this lesson, you will learn about how to develop social solutions. You will learn about the permissions
required when developing a social app, and you will learn about how to follow and like entities by using
code.
Lesson Objectives
 Configure app permissions for social solutions.
 Describe the concepts of actors.

 Describe how to follow actors.
 Manage following of a social actor.
 Like posts on a newsfeed.
Demonstration: Tagging and Following Entities by Using Out-of-the-Box

Functionality
Like many other social sites, SharePoint provides mechanisms for users to tag content and to follow
content. This demonstration shows you how you can use the out-of-the-box functionality in SharePoint
2013. When you develop solutions to extend the social workload, you will typically extend the out-of-the-
box functionality.
Demonstration Steps
4. In Internet Explorer, in the address bar, type http://project.contoso.com, and then press Enter.
5. On the Quick Launch menu, click Newsfeed.
6. On the Newsfeed page, in the Start a conversation text box, type This is a #newtag, and then click
Post.
7. In the new post, click #newtag.
8. On the About #newtag page, click follow.
10. In the I’m following list, above tags, click the number 1.
11. Review the Followed #Tags list.

Configuring App Permissions

As with any app development, it is important that
you configure the correct app permissions requests
for a social app. Failure to request the necessary
permissions will result in your app not functioning
as expected.
For social solutions, the main app permissions that

you need to use are:
 User Profiles (http://sharepoint/social/tenant).

This permission scope provides read-only
access to user profile properties.
 Core Social (http://sharepoint/social/core). This

permission scope provides read and write access to followed content and shared metadata used by
the micro blogging features. This applies to data stored on the user’s personal site (My Site).
 Microfeed (http://sharepoint/social/microfeed). This permission scope provides access to a user’s or

team’s newsfeed. This is required to access a newsfeed on either a personal site (My Site), or any other
site that has the Newsfeed Feature enabled.
To simplify development, you can choose to use the Tenant scope (http://sharepoint/content/tenant).
The Tenant scope provides access to the whole tenancy; this includes the Core Social and Microfeed
permission scopes. After development and for final testing you should use more restrictive permission
scopes.
For final testing and production, you should deploy your app by using an app catalog. If you attempt to
debug an app that uses social features without specifying the Tenant scope, you must deploy your app
by using an app catalog. You may get unexpected errors if you do not use an app catalog.
Note: When you choose permissions levels (for example, read or read and write), if you
choose the full control permission level you cannot deploy your app to Office 365. The office
store blocks any app that request the full control level for any permission.
Because many social solutions make use of search, you may also need to specify the Search scope
(http://sharepoint/search), and specify the QueryAsUserIgnoreAppPrincipal permission level. This
permission enables an app to perform a search query by using the permissions of the user, as opposed to
the permissions granted to the app.
Actors
When you develop social solutions, entities such as
users, sites, tags, and documents are referred to as
actors. Actions that you can perform in the social
workload are normally performed on a set of actors.
For example, an actor can follow another actor
much as a user can follow a site.
To work with actors, you normally use the

SocialActor class. Some of the most frequently
used properties of the SocialActor class include:
Property Actor Type Description
AccountName User The account name of the specified user.
ActorType All The type of the actor 0=User 1=Document 2=Site 3=Tag.
CanFollow All A Boolean value to determine if the current user is able to

follow the specified actor.
ContentUri Document/Site The URI of the specified document.
Id All The unique id of the specified actor.
IsFollowed All A Boolean value showing whether or not the current user
follows the specified actor.
Name User The name of the specified user
TagGuid Tag The unique GUID that identifies the specified tag.
Additional Reading: For more information about the properties available in the
SocialActor class, see the SocialActor members page at
http:/go.microsoft.com/fwlink/?LinkId=321957
Following Entities
Commonly, a user may choose to follow an actor.
You can create solutions that enable a user to
follow actors. In SharePoint 2013, you should
normally develop a client-side application to enable
a user to follow an actor. You can use REST, the
.NET Client-side Object Model, or the JavaScript
Object Model to follow an actor.
In addition to following an actor by using custom

solutions, by default most sites have Follow buttons
for various entities. You can disable these buttons
by disabling the Follow Content feature. If an
administrator has disabled the Follow Content Feature, you can still follow actors on that site by using a
custom solution.
Following an Actor by Using REST

An actor can be followed in two ways by using REST:
 Modifying the request URL
 Adding information to the request body of an AJAX call.
Modifying the URL Structure

The endpoint for following an actor uses the SocialRestFollowingManager resource and the
PeopleManager resource.
http://<appWebUrl>/_api/social.following/follow<feedOptions>
The feedOptions that follow depend on the type of actor that you want to follow. The following table
shows the parameters used for each type of actor:
Actor URL Structure
User http://
<appWebUrl>/_api/social.following/follow(ActorType=0,AccountName=@v,Id=null)?@v
='contoso\pat’
Document http://<appWebUrl>/_api/social.following/follow(ActorType=1,ContentUri=@v,Id=null)?
@v='http://server/Shared%20Documents/fileName.docx’
Site http://<appWebUrl>/_api/social.following/follow(ActorType=2,ContentUri=@v,Id=null)?
@v='http://server/site’
Tag http://<appWebUrl>/_api/social.following/follow(ActorType=3,TagGuid='19a4a484-
c1dc-4bc5-8c93-bb96245ce928',Id=null)
Note: The @ alias is used to pass special characters.
Modifying the AJAX request body

Alternatively, you can follow an actor by modifying the request body of an AJAX call. The required
parameters depend on the type of actor.
User
'actor': {
'__metadata': {
type: 'SP.Social.SocialActorInfo'
},
'ActorType': 0,
'AccountName': "domain\\user",
'Id': null
}
Document
'actor':{
'__metadata':{
'type': 'SP.Social.SocialActorInfo'
},
'ActorType': 1,
'ContentUri': 'http://server/Shared%20Documents/File.docx',
'Id':null
}
Site
'actor':{
'__metadata':{
},
'ActorType':2,
'ContentUri':'http://siteCollection/site',
'Id':null
}
Tag
'actor':{
'__metadata':{
},
'ActorType': 3,
'TagGuid': '69a4c382-b1dc-4bc5-3c93-eb96245ce923',
'Id':null
}
Note: The TagGuid cannot be obtained by using REST. You must use either the .NET Object
Model or the JavaScript Object Model.
The following code example shows how to follow a user by using REST:
Follow Users by Using REST

function followUserURL() {
$.ajax({
url: appWebUrl +
"/_api/social.following/follow(ActorType=0,AccountName=@v,Id=null)?@v='contoso\\pat'",
type: 'POST',
headers: {
'accept': 'application/json;odata=verbose',
'content-type': 'application/json;odata=verbose',
'X-RequestDigest': $('#__REQUESTDIGEST').val()
},
success: followSuccess,
error: followFail
});
}
function followUserRequestBody() {
$.ajax({
url: appWebUrl + "/_api/social.following/follow",
type: 'POST',
'actor': {
'__metadata': {
type: 'SP.Social.SocialActorInfo'
},
'ActorType': 0,
'AccountName': 'contoso\\pat',
'Id': null
}
}),
headers: {
'X-RequestDigest': $('#__REQUESTDIGEST').val()
},
success: followSuccess,
error: followFail
});
}
function followSuccess(data) {
var followResult = data.d.Follow;
}
FollowResult
The request returns a result of type SP.Social.SocialFollowResult. The following table shows the possible
values that can be returned.
Status Result
0 OK
1 AlreadyFollowing
2 LimitReached
3 InternalError
Following an Actor by Using the .NET Client Object Model

When following actors by using the .NET Client Object Model, the SocialFollowingManager and
SocialActorInfo classes are required.
SocialFollowingManager
The SocialFollowingManager class is similar to the SocialRestFollowingManager resource. It is used to
manage the list of actors that the current user follows. A key subset of the methods available in the
SocialFollowingManager class include:
Method Description Parameters
Follow Adds the specified actor to the current user’s SocialActorInfo – The actor
list of followed actors. that is to be followed.
IsFollowed Returns true if the current user is already SocialActorInfo – The actor
following the specified actor. that is being queried.
StopFollowing Removes the specified actor from the SocialActorInfo – The actor
current user’s list of followed actors. that is to be unfollowed.
SocialActorInfo
The SocialActorInfo class determines which type of actor you want to deal with and has the following
properties available.
Property Actor Type Description
AccountName User The account name of the specified user (e.g. contoso\pat).
ActorType All The type of the specified actor.
ContentUri Site/Document The URI of the specified site or document.
Id All The id of the specified actor.
TagGuid Tag The GUID of the specified tag.
The following code example shows how to follow a user by using the .NET Object Model:
Follow a User by Using the .NET Object Model

ClientContext clientContext = new ClientContext(serverUrl);
SocialFollowingManager followingManager = new SocialFollowingManager(clientContext);
SocialActorInfo socialActorInfo = new SocialActorInfo();

socialActorInfo.ActorType = SocialActorType.User;
socialActorInfo.AccountName = "contoso\\pat";
followingManager.Follow(socialActorInfo);
clientContext.ExecuteQuery();
Following an Actor by Using the JavaScript Object Model

Following an actor by using the JavaScript Object Model is very similar to following an actor by using the
.NET Client Object Model.
The following example shows how to follow a user by using the JavaScript Object Model:
Follow a User by Using the JavaScript Object Model

var followingManager = new SP.Social.SocialFollowingManager(clientContext);
var actorInfo = new SP.Social.SocialActorInfo();

actorInfo.set_accountName("contoso\\pat");
followingManager.follow(actorInfo);
clientContext.executeQueryAsync(followSuccess, followFail);
Managing Following
Any site, tag, or document can be followed. For
these types of actors, you will normally want to
provide a toggling option that switches state
between follow and stop following. When your app
starts, you should be sure that any controls to
enable a user to follow an actor are in the correct
initial state.
In addition to determining the correct initial state,

you should also perform checks to confirm that an
actor can be followed by a particular user. For
example, a user cannot follow themselves; if you are
adding a follow button next to a username, you
should not add a button if the current user’s name is displayed.
For users, you can obtain actor properties to determine what are valid options.
Managing Following by Using REST

You can use REST, to obtain key properties named CanFollow and IsFollowing. These properties return
Boolean values to determine if an actor can be followed and if the current user is already followed the
actor. After these values are known, a call to follow or stop following the given user can be made if
necessary.
The following code example shows how to manage following by using REST:
Manage Following by Using REST.

var actorInfo = getActorInfo();
if (actorInfo.CanFollow == true) {
if (actorInfo.isFollowed == false) {
followUser(actorInfo.AccountName);
} else {
stopFollowingUser(actorInfo.AccountName);
}
}
Managing Following by Using the .NET Client Object Model

The following example shows how to toggle the following state for a specified user by using the .NET
Object Model:
Manage Following a User by Using the .NET Object Model

SocialFollowingManager followingManager = new SocialFollowingManager(clientContext);
void CanFollow(socialActor) {
If (socialActor.CanFollow == true) {
SocialActorInfo socialActorInfo = new SocialActorInfo();

socialActorInfo.ActorType = SocialActorType.User;
socialActorInfo.AccountName = socialActor.AccountName;
FollowToggle(socialActorInfo);
}
void FollowToggle(socialActorInfo) {
ClientResult<SocialFollowResult> result = followingManager.Follow(socialActorInfo);
if (result.Value == SocialFollowResult.AlreadyFollowing)
{
followingManager.StopFollowing(socialActorInfo);
}
}
Managing Following by Using the JavaScript Object Model

The following code example shows how to toggle the following state for a specified user by using the
JavaScript Object Model:
Managing Following a User by Using the JavaScript Object Model

var followingManager = new SP.Social.SocialFollowingManager(clientContext);
var actorInfo;
function follow(socialActor) {
var socialActor = getSocialActor();
if(socialActor.get_canFollow() == true) {
actorInfo = new SP.Social.SocialActorInfo();

actorInfo.set_accountName(socialActor.get_accountName());
clientContext.executeQueryAsync(followToggle, followFail);
}
}
function followToggle() {
var isFollowed = followingManager.isFollowed(actorInfo);
if (isFollowed.get_value()==true) {
followingManager.stopFollowing(actorInfo);
} else {
followingManager.follow(actorInfo);
}
clientContext.executeQueryAsync(followToggleSuccess, followToggleFail);
}
Liking Posts
As well as following actors, you can also like posts.
Any post you follow appears in the Likes section of
your My Site. You don’t have to be following the
user in order to like their post. While following an
actor gives you updates about that actor, liking a
post is more of a way of keeping a history posts or
replies that interest you.
Liking and following are very similar; before you like

a post, you must determine if the post can be liked
(not all posts on a feed can be liked). For example, a
post stating that a user has started following
another user cannot be liked. This can be
determined by getting the LikerInfo property for the post. If the LikerInfo property is null, then that post
cannot be liked.
After you have determined if the post can be liked, you must determine if the current user already likes
that post. The IncludesCurrentUser property defined in LikerInfo provides a Boolean value to indicate if
that post is currently liked or not.
The following example shows how to like a post by using the JavaScript Object Model. The code is very
similar to following a post. Liking a post by using the .NET Client Object Model and REST are not included
here, but follow the same pattern as following a post in the previous topics:
Like a Post by Using the JavaScript Object Model

var postId = rootPost.get_id();
var likerInfo = rootPost.get_likerInfo();
if (likerInfo != null) {
if (likerInfo.get_includesCurrentUser() == false) {
feedManager.likePost(postId);
clientContext.load(feedManager);
clientContext.executeQueryAsync(postLiked, postLikedFail);
}
else {
feedManager.unlikePost(postId);
clientContext.executeQueryAsync(postUnliked, postUnlikeFail);
}
}
Lesson 3
Working with Feeds
In this lesson, you will learn how to work with feeds in SharePoint 2013. You will learn how to retrieve a
feed from either a My Site or another site, and then you will learn how to post messages to a feed. Finally,
this lesson covers how to include hashtags and mentions in a newsfeed post.
Lesson Objectives
 Describe how to use newsfeeds.
 Write code to retrieve a newsfeed.

 Write code to submit a post.
 Include mentions and tags in a feed post.
Introducing Feeds
SharePoint 2013 introduces newsfeeds. Users can
post updates to a feed, as well as links to pictures
and sites.
A user’s My Site includes a newsfeed by default, as

do some other site templates. However, they are
not included by default on all site templates. You
can add a newsfeed to an existing site by activating
the Site Feed Feature, or add a newsfeed in an
existing site definition by using a Feature Stapler or
by referencing the Site Feed Feature in a new site
definition.
When you are working with feeds, you should be

aware that the implementation details for site newsfeeds and user newsfeeds (on My Sites) is subtly
different; for example they use different content types. The implementation difference does not make any
change to the APIs that you use to interact with the newsfeed. However, it can make a difference if you
are accessing a post directly, for example by using list APIs, or if you search to retrieve newsfeed posts.
Retrieving Feeds
A feed consists of a number of threads. Each thread
consists of a root post and any number of replies.
To retrieve a feed, you must first retrieve the social
feed that contains details about the threads
included in the feed, in addition to other actor
information such as actor information for post
authors, as well as information on any tags or
mentions included in a post.
REST
To retrieve a feed by using REST, you must make a
GET request to the site that is hosting the
SharePoint Project/App. The structure of the site
URL depends on which type of entity you want to retrieve a feed from.
Actor URI Structure
Current http://<appWebUrl>/_ api/social.feed/my/feed

User
Differe http://<appWebUrl>/_ api/social.feed/actor(item='contoso\\pat')/feed

nt User
Site http://<appWebUr>l/_api/social.feed/actor(item=@v)/feed?@v='http://<teamSiteUri>/new
sfeed.aspx’
The code example shows how to retrieve the current user’s personal feed by using REST:
Retrieve the Current User’s Personal Feed by Using REST

function retrieveMyPersonalFeed() {
$.ajax({
url: appWebUrl + "/_api/social.feed/my/feed",
headers: {
'accept': 'application/json;odata=verbose'
},
success: retrieveMyFeedSuccess,
error: retrieveMyFeedFail
});
}
function retrieveMyFeedSuccess(data) {
var feedThreads = datat.d.SocialFeed.Threads.results;
}
.NET Client Object Model

The Microsoft.SharePoint.Client.Social namespace gives you access to the SocialFeedManager class.
SocialFeedManager
The SocialFeedManager class provides the gateway to access social elements by using the .NET Client
Object Model. Methods are provided to create posts, modify existing threads, and access the social feeds
of users and sites.
A key subset of the methods available in the SocialFeedManager class include:
Name Description Parameters
CreatePost Creates a post to appear on a targetID – A string that contains either

specified feed or as a reply to a the thread ID of a post, the URI of a site
specified post. feed, or null to publish to the current
user’s personal feed.
SocialPostCreationData – An object that
contains content and information that is
to be included in the post.
GetFeed Gets the current user’s activity feed. SocialFeedType – The type of feed that is
The activity of content and people to be retrieved.
followed by the current user can SocialFeedOptions – Options to define
also be retrieved. how the feed should be retrieved.
GetFeedFor Retrieves a feed for a specified site actorId – A string that contains either the
or user. account name or email address of a user
or the feed address of a site.
Additional Reading: For more information about the SocialFeedManager class, see the
SocialFeedManager members MSDN page at http://go.microsoft.com/fwlink/?LinkId=321960
The following code example shows how to retrieve the current user’s personal feed by using the .NET
Client Object Model:
Retrieve Current User’s Personal Feed by Using the .NET Client Object Model
SocialFeedManager feedManager = new SocialFeedManager(clientContext);
SocialFeedOptions feedOptions = new SocialFeedOptions();

feedOptions.MaxThreadCount = 5;
ClientResult<SocialFeed> myPersonalFeed = feedManager.GetFeed(SocialFeedType.Personal,

feedOptions);
var myPersonalFeedThreads = myPersonalFeed.Value.Threads;
JavaScript Object Model

The following example shows how to retrieve the current user’s personal feed by using the JavaScript
Object Model:
Retrieve the Current Users Personal Feed by Using the JavaScript Object Model
var personalFeed;
function getMyPersonalFeed() {
var feedManager = new SP.Social.SocialFeedManager(clientContext);
var feedOptions = new SP.Social.SocialFeedOptions();

feedOptions.set_maxThreadCount(5);
personalFeed = feedManager.getFeed(SP.Social.SocialFeedType.personal, feedOptions);

clientContext.executeQueryAsync(getMyPersonalFeedSuccess, getMyPersonalFeedFail);
}
function getMyPersonalFeedSuccess() {
var personalfeedThreads = personalFeed.get_threads();
}
Demonstration: Retrieving a Newsfeed by Using the JavaScript Object

Model
One of the most basic operations you can perform when you work with social features in SharePoint 2013
is to retrieve a user’s newsfeed. To retrieve the newsfeed you must use the SocialFeedManager, which
you will use for many social-based programming tasks. In this demonstration you will see a simple
application that uses the JavaScript object model to retrieve a user’s newsfeed and to display the resulting
threads on a page. You will also review the permissions granted to the app to enable the app to access
the user’s newsfeed.
Demonstration Steps
3. On the Start screen type Visual Studio, and then click Visual Studio 2012.
4. In Visual Studio, on the FILE menu, point to Open and then click Project/Solution.
5. In the Open Project dialog box, browse to E:\Democode\NewsfeedApp, click NewsfeedApp.sln,

and then click Open.
6. In Solution Explorer, expand NewsfeedApp, expand Pages, and then double-click Default.aspx.
7. Review the contents of the Default.aspx page. Notice the additional JavaScript file reference for the
sp.userprofiles.js script file, and the empty posts div.
8. In Solution Explorer, expand Scripts, and then double-click App.js.
9. Review the contents of the App.js file. The getNewsFeed and getNewsFeedSuccess functions, load
the newsfeed for the current user and add the root post of each of the newsfeed threads to the page.
10. Notice the code that invokes the getNewsFeed function when the page loads, and then
subsequently every five seconds.
11. In Solution Explorer, double-click AppManifest.xml.
12. In the App Manifest designer, on the Permissions tab, notice that this app requires the User Profiles
(Social) and Tenant permissions to enable it to access the user’s newsfeed.
14. In Internet Explorer, click Trust It.
15. In a new instance of Internet Explorer, browse to http://my.contoso.com. Arrange the two instances
of Internet Explorer so that they can be seen side by side.
16. On the Newsfeed page, in the Start a conversation box, type A new post and then click Post.
17. Notice that the post appears in the newsfeed on the My Site newsfeed, and that the post also appears
in the app (the Newsfeed Posts page).
18. On the Newsfeed page, under A new post, click Reply.

19. In the Reply text box, type A reply, and then under the Reply text box, click Post.
20. Notice that although the reply is displayed on the My Site, it is not displayed in the app. This is
because the app is only displaying the root post for each thread.
21. Close all open windows
Posting to a Feed
You can post in the context of the current user. A
user cannot create a root post on another user’s My
Site; however, you can post a root post on the
current user’s My Site, or on a SharePoint site. You
can also post a reply to an existing post. You can
reply to a post on either a SharePoint site or a My
Site, including another user’s My Site.
Posting by Using REST

To post to the current user’s My Site, use the
following endpoint URI structure:
 http://<appWebUrl>/_api/social.feed/my/feed/
post
To post to the newsfeed of a specific SharePoint site, use the following endpoint URI structure:
 http://<appWebUrl>/_api/social.feed/actor(item=@v)/feed/post?@v='http://project.contoso.com/ne
wsfeed.aspx’
The following code example shows how to send a post to the current user’s My Site feed by using REST:
Send a Post to Current User’s My Site Feed by Using REST

$.ajax({
url: appWebUrl + "/_api/social.feed/my/feed/post",
type: 'POST',
'restCreationData': {
'creationData': {
'__metadata’: {
'type': 'SP.Social.SocialPostCreationData'
},
'ContentText': 'Post sent by using REST',
'UpdateStatusText': false
}
}
}),
headers: {
'X-RequestDigest': $('#__REQUESTDIGEST').val(),
},
success: postSuccess,
error: postFail
});
Posting by Using the .NET Client Object Model

When posting to a feed by using the .NET Client object model, you will need to use the
SocialPostCreation Data class and the SocialFeedManager class.
SocialPostCreationData
The SocialPostCreationData class contains information about the post that is to be posted to the
specified news feed. A key subset of the properties provided in this class include:
Property Parameters
ContentItems SocialDataItem[] – An array of SocialDataItem objects such as mentions

and tags.
ContentText string – The text that is to be included in the post.
The following code example shows how to send a post to the current user’s My Site feed by using the
.NET Client Object Model:
Post to the Current User’s My Site by Using the .NET Client Object Model
SocialPostCreationData postCreationData = new SocialPostCreationData();

postCreationData.ContentText = “Post sent by using CSOM”;
feedManager.CreatePost(null, postCreationData);
Posting by Using the JavaScript Object Model

The following code shows how to send a post to the current user’s My Site feed by using the JavaScript
Object Model:
Post to the Current User’s My Site Feed by Using the JavaScript Object Model
var postCreationData = new SP.Social.SocialPostCreationData();

postCreationData.set_contentText("Post sent by using JSOM");
feedManager.createPost(null, postCreationData);
clientContext.executeQueryAsync(postSent, postFailed);
Adding Mentions and Tags to a Feed Post

Mentions and tags make it easy for a user to refer
to another user or to reference a topic. When you
develop custom social solutions you may want to
enable users to include mentions or tags in posts.
When you submit a post that includes a tag or a
mention, you must add each of the tags or
mentions to an array of SocialDataItem instances.
The items should be added to the array in the same
order that they appear in the post. You should
replace the tags and mentions with placeholders in
the format {0} (for developers familiar with
Microsoft Visual C#, this is the same format as the
String.Format method). For example, if a user types @Pat Hello #World, you should submit @{0} Hello
{1} with an array of SocialDataItem instances that contain Pat and #World.
Note: When a new hashtag is used in a post, it is added to the SharePoint tag library.
The SocialDataItem Class

A SocialDataItem can be a site, document, user mention, or tag reference. Because there are different
types of SocialDataItem objects available, the SocialDataItem class contains the following properties:
Property Actor Type Parameters
AccountName User string – The account name of the user to be mentioned in

the post.
ItemType All SocialDataItemType – The type of item that is to be added

to the post.
Text Tag string - The text of the gat that is to be added to the post.
Uri Site/Document Uri - The Uri of the site or document that is to be added to
the post.
Additional Reading: For more information about the SocialDataItem class, see the
SocialDataItem members MSDN page at http://go.microsoft.com/fwlink/?LinkId=321965
REST
The following code example shows how to create a hashtag and mention and add them to a post by
using REST:
Add a Hashtag and Mention to a Post by Using REST

var mention = new SP.Social.SocialDataItem();
mention.AccountName = "contoso\\pat";
mention.ItemType = 0;
var hashtag = new SP.Social.SocialDataItem();

hashtag.ItemType = 3;
hashtag.Text = "#REST";
var postItems = new Array();

postItems.push(mention);
postItems.push(hashtag);
$.ajax({
url: appWebUrl + "/_api/social.feed/my/feed/post",
type: 'POST',
'creationData': {
'__metadata': {
},
'ContentItems': {
'results': postItems
},
'ContentText': '@{0} Post sent by using {1}',
}
}
}),
headers: {
'X-RequestDigest': $('#__REQUESTDIGEST').val(),
},
success: postWithItemsSuccess,
error: postWithItemsFail
});
.NET Client Object Model

The following code example shows how to add a mention and hashtag to a post by using the .NET Client
Object Model:
Add a Mention and Hashtag to a Post by Using the .NET Client Object Model
ClientContext = new ClientContext(serverUrl);
SocialDataItem mention = new SocialDataItem();

mention.ItemType = SocialDataItemType.User;
mention.AccountName = "contoso\\pat";
SocialDataItem hashtag = new SocialDataItem();

hashtag.ItemType = SocialDataItemType.Tag;
hashtag.Text = "#CSOM";
SocialPostCreationData postCreationData = new SocialPostCreationData();

postCreationData.ContentText = "@{0} Post sent by using {1}";
postCreationData.ContentItems = new SocialDataItem[2] {mention, hashtag};
feedManager.CreatePost(null, postCreationData);
JavaScript Object Model

The following code example shows how to add a mention and hashtag to a post by using the JavaScript
Object Model:
Add a Mention and a Hashtag to a Post by Using the JavaScript Object Model
var mention = new SP.Social.SocialDataItem();
mention.set_itemType(SP.Social.SocialDataItemType.user);
mention.set_accountName("contoso\\pat");
var tag = new SP.Social.SocialDataItem();

tag.set_itemType(SP.Social.SocialDataItemType.tag);
tag.set_text("#JSOM");
var socialDataItems = [mention, tag];

var postCreationData = new SP.Social.SocialPostCreationData();

postCreationData.set_contentText("@{0} Post sent by using {1}");
postCreationData.set_contentItems(socialDataItems);
feedManager.createPost(null, postCreationData);
clientContext.executeQueryAsync(postSent, postFailed);
Lab: Creating a Social App Part

Scenario
Contoso managers want to encourage users to use the social features in SharePoint. To simplify the
process, they want to be sure that comments made about a particular project are always displayed on the
corresponding project site. To facilitate this, they want to add an App Part to each project site to enable
users to post messages related to that project to a site newsfeed. However, instead of simply posting a
message to the site newsfeed, the App Part should append the project code to every post as a hashtag.
The project code for each project site is stored in the site property bag. In addition to customizing the
post process, the App Part should further extend the default functionality by using the search service to
retrieve any posts that users have added to their My Site newsfeed that includes the project code as a
hashtag. The App Part should also display these posts inline with posts from the site newsfeed.
Objectives
 Use REST to retrieve a site newsfeed.
 Use REST to add a post to a site newsfeed.
 Use the JavaScript Object Model (JSOM) to search for newsfeed posts on My Site newsfeeds.
Lab Setup

Exercise 1: Displaying a Project Site Newsfeed

Scenario
In this exercise you will add code to an existing app part to retrieve a newsfeed from a SharePoint project
site that has the newsfeed features enabled. First you will configure the permissions required for access to
the social features, and then you will add the code to load and display the newsfeed before testing the
app.
1. Set Permission Requirements
2. Add Code to Load the Project Site Newsfeed
3. Test the App Part
 Task 1: Set Permission Requirements

3. Open up the starter solution located at E:\Labfiles\Starter\ContosoFeedApp.

4. Set the following app permissions:
Scope Permission
Tenant Write
User Profiles (Social) Read
Note: The Tenant permission simplifies the debugging process. In a production app you
should use the most restrictive permissions requirements that are necessary for your app.
 Task 2: Add Code to Load the Project Site Newsfeed

1. In the App.js file, locate the comment // TODO: Add code to load the site's newsfeed.
2. Use the Utilities.appWebUrl and Utilities.hostWebUrl properties to make an Ajax call to retrieve
the project site newsfeed.
3. If successful, the Ajax GET request must return the thread results of the feed in reverse order, set the
feed to Contoso.NewsfeedApp.feedPosts and update the display.
4. Locate the // TODO: Add code to update the newsfeed when the app launches. comment.
5. After the comment you have just located, add code to invoke the
Contoso.NewsfeedApp.updateFeed function when the app launches. This will update the display
with the posts you retrieved by using the Ajax GET request.

1. Start the app without debugging.
2. On the Project Site home page, add the ContosoFeedAppPart Title app part to the top section of
the page.
3. Verify that a newsfeed is displayed with a single post, with the message Welcome to the project site
for project 2822.
Results: After completing this exercise, you should have modified an app part to display a newsfeed from
a project site.
Exercise 2: Posting a Message to a Newsfeed

Scenario
In this exercise you will modify the app part to include the necessary controls and code to post a message
to the project site newsfeed. First you will add controls to the page to enable a user to type a message
and to submit that message. Then you will add code that parses the message typed by the user to identify
any hashtags included in the message. The code will also append a hashtag to the message by using a
utility method already provided in the app code to retrieve the project code from the project site property
bag. You will then use an asynchronous request to submit the new post. Finally, you will test the app part.
1. Add Controls to the User Interface
2. Add Code to Submit a Post
 Task 1: Add Controls to the User Interface

1. Open the designer for the ContosoFeedAppPart app part.
2. In the Source view locate the  comment.
3. After the comment, add a text area to the app part with the following attributes:
Attribute Value
Id StatusTextArea
cols 50
rows 2
4. Next to the text area, add a button to the app part with the following attributes:
Attribute Value
Id PostStatus
Type button
5. In the App.js file, locate the comment // TODO: Add code to add a click event handler to the
post button.
6. After the comment, add code to invoke the Contoso.NewsfeedApp.post function when the user
clicks the PostStatus button.
 Task 2: Add Code to Submit a Post

1. In the App.js file, review the getProjectCode function.
This function sets the Utilities.projectSiteCode variable by retrieving the project code that is stored
in the site property bag. This function is self-invoking, and so runs as soon as the app starts.
2. Locate the following comment // TODO: Add code to send the new post to SharePoint.
3. Add code to retrieve content from the StatusText text area. You should store the value in a new
variable named userContent.
4. Add code to append the project site code to the userContent variable as a hashtag. Use the
Utilities.projectSiteCode property to retrieve the project site code.
5. Add code to declare a new variable named tags, and initialize it as a new array.
6. Add code to initialize a new variable named tagCount to 0.
7. Add code to parse the userContent variable. The code should split the string into words, and then
replace any hashtags with a placeholder in the format {0}. You should create a new
SP.Social.SocialDataItem instance for each hashtag. You should add the SocialDataItem instance to
the tags array, and increment the tagCount variable to track the number of hashtags in the content.
When you replace the tag with a placeholder you should use the current value of tagCount as the
number in the placeholder. The result of your code should be an array of SocialDataItem objects and
a string variable that contains the manipulated post content.
8. Add an Ajax POST request that submits the post containing the hashtag items to the host web. Use
the Utilities.appWebUrl and Utilities.hostWebUrl properties to construct the REST endpoint
address.
9. Add code to clear the contents of the StatusText text area.
10. Locate the following comment // TODO: Add code to update the feed after a post is successfully
added.
11. After the comment, add code to update the feed after the post is submitted successfully.

2. Use the app to send the message Sent from the app, and then verify that the newsfeed is updated
with the message, and that #P2822 has been appended to the end of the post.
3. View the newsfeed for the site by viewing the out-of-the-box newsfeed and verify that the post
appears correctly.
Results: After completing this exercise, you should have added controls and code to an app part to
support posting a message to a newsfeed.
Exercise 3: Using Search to Retrieve Newsfeed Posts

Scenario
In this exercise you will add code to the app part to supplement posts from the newsfeed on the project
site with posts on users’ My Sites. You will use the search service to retrieve the posts from users’ My Sites.
You will review the code that displays the newsfeed on the app part, and add necessary helper functions
to retrieve additional properties related to the posts returned by the search service. You will then test the
app.

1. Modify the getSiteFeedSuccess Function to Use Search
2. Add Code to Retrieve Actor Information
 Task 1: Modify the getSiteFeedSuccess Function to Use Search

1. Modify the app to request the Search app permission scope with the permission level Query
asUserIgnoreAppPrincipal.
2. In the getSiteFeedSuccess function, add code to define a new variable named queryString, and
initialize it to "(ContentTypeId:0x01FD4FB0210AB50249908EAA47E6BD3CFE8B* OR
ContentTypeId:0x01FD59A0DF25F1E14AB882D2C87D4874CF84* OR
ContentTypeId:0x012002* OR ContentTypeId:0x0107* OR
WebTemplate=COMMUNITY)owstaxIdMetadataAllTagsInfo:" + Utilities.projectSiteCode
Note: The query string specifies that the search result must be a post on a My Site or
community site. The query string also states that the items must be tagged with the project site
code. You may find it easier to copy the query string from the solution code.
3. Add code to create a new instance of the

Microsoft.SharePoint.Client.Search.Query.KeywordQuery class named keywordQuery. You
should use the Utilities.clientContext property to initialize the variable.
4. Add code to set the queryText property of the keywordQuery object to the queryString variable.
5. Add code to retrieve the sortList property of the keywordQuery object, and store it in a new
variable named sortList.
6. Add code to add a new entry to the sortList object. The new entry should specify that the results
should be sorted by the last modified date (LastModifiedTime), and should be in ascending order
(Microsoft,SharePoint.Client.Search.Query.SortDirection.Ascending).
7. Add code to set the enableSorting property of the keywordQuery object to true.
8. Add code to create a new instance of the

Microsoft.SharePoint.Client.Search.Query.SearchExecutor class named searchExecutor. You
should use the Utilities.clientContext property to initialize the variable.
9. Add code to declare a new variable named results, and initialize it to the result of calling the
executeQuery function of the searchExecutor object by using the keywordQuery object as a
parameter.
10. Remove the existing call to the Display.updateDisplay function from the getSiteFeedSuccess
function.
11. Add code to call the executeQueryAsync function of the Utilities.clientContext object. The
function should set the Contoso.NewsfeedApp.searchResults property to the search results from
the results.m_value.ResultTables[0].ResultRows property. It should then set the
Contoso.NewsfeedApp.feedPosts property to the feedPosts property. Finally, it should invoke the
Display.updateDisplay function. If the request fails, the call should display an error message in an
alert window.
 Task 2: Add Code to Retrieve Actor Information

1. Review the code in the updateDisplay function.
In the updateDisplay function, data from both the newsfeed and search results are merged. Because
the results from the search service are not in the same format as the posts from the current site, the
updateDisplay function uses a utility function named getActorInfo to retrieve missing information
about the post author.
2. Locate the following comment // TODO: Review the addToFeed function.
3. Review the code in the addToFeed function. In this function, individual posts are parsed and HTML
markup added to a variable for display on the page.
4. Locate the following comment // TODO: Add code to retrieve the actor for the specified account.
5. Add code to make an Ajax GET request to retrieve the actor information for the user account passed
as a parameter to the function. You should specify that the request should run synchronously, and
you should display the error message in an alert box if the request fails.

2. Add the app part to the top section of the project site home page.
3. Verify that the feed now includes a message from Pat Coleman asking for help on a case study she is
producing. This post is from Pat’s My Site newsfeed.
Results: After completing this exercise, you should have modified the app part to display posts retrieved
by using the search service.

In this module you learned about how to extend the social workload. You learned how SharePoint 2013
has changed from earlier versions, and you learned the requirements for configuring an environment for
social solutions. You then learned about the app permissions that you need when developing social
solutions, before learning about some of the most common features used in social apps, including how to
use following, mentions, and likes, and how to work with feeds.
Review Question(s)
Test Your Knowledge

Question
Which of the following service applications is not commonly required when developing a
social app?
Managed Metadata Service
User Profile Service Application
Managed Metadata Service
Search Service Application
Word Automation Services
Test Your Knowledge

Question
Which of the following is not a type of actor?
Site
Document
Post
User
Tag
Statement Answer
A user can add a root post on a different

user’s My Site feed.
14-1
Module 14
Monitoring and Troubleshooting Custom SharePoint
Solutions
Contents:
Lesson 1: Debugging SharePoint Apps in Visual Studio 14-2
Lesson 2: Diagnosing Faults in Deployed Apps 14-9
Lesson 3: Testing Performance and Scalability 14-15
Lab: Enabling ASP.NET Tracing 14-22
Module Overview
Like any coded solutions, Microsoft® SharePoint® 2013 apps and solutions may contain bugs from a
variety of sources. You should aim to identify and eliminate as many bugs as possible during the
development phase of your project. There are versatile tools to help you do this in both Microsoft Visual
Studio® and Internet Explorer® and you should incorporate debugging into your development workflow
early in the project. However, some bugs may make it through testing and only become apparent when
the solution or app is deployed. To diagnose these, you can use tracing techniques that log error details.
With these details, you can remove the bugs in subsequent versions. In addition to debugging techniques,
this module introduces methods that you can use to improve the performance and scalability of solutions
and apps.
Objectives
 Describe how to identify, diagnose, and remove bugs in SharePoint apps during development.
 Describe how to record information about issues that arise in deployed SharePoint apps.
 Describe how developers optimize the performance of SharePoint apps by implementing best
practices, measuring performance, and load testing.
14-2 Monitoring and Troubleshooting Custom SharePoint Solutions
Lesson 1
Debugging SharePoint Apps in Visual Studio
In the perfect scenario, all bugs are removed during the development of a project and the resulting
solutions work precisely as designed in the production environment. By incorporating the Visual Studio
and Internet Explorer debugging tools into your development processes, and by enforcing a strict testing
regime, you can approach this ideal and produce high-quality software. In this lesson, you will see how to
use these debugging tools and how to debug code in the unique architecture used by SharePoint apps.
Lesson Objectives
 Configure a SharePoint site for debugging code during the development of SharePoint solutions and
SharePoint-hosted apps.
 Configure a remote web for debugging code during the development of cloud-hosted apps.
 Use Visual Studio and Internet Explorer to debug JavaScript code in SharePoint apps.
 Validate data returned from calls to SharePoint REST endpoints.
 Debug remote event receivers in cloud-hosted apps.
Configuring a SharePoint Site for Debugging

In Visual Studio, when you run an application in
debugging mode, execution will stop when an
exception is raised. At this point, you can examine
the values of variables and the details of the
exception to determine what went wrong. When
execution has stopped, you can use the following
tools in Visual Studio to investigate any problems:
 The Output window. Error messages associated

with any exception are shown in the Output
window. These messages usually give general
help to diagnose the problem.
 The Immediate window. You can use this

window to evaluate expressions that you think might be causing the problem. For example, if you
think the variable myVar may be null, you can type "=myVar" in the Immediate window to obtain its
actual value.
 The Call Stack Window. This window shows all the current calls in the call stack. This can be extremely
helpful when there are many methods in different code files executing simultaneously.
 The IntelliTrace® window. The IntelliTrace window shows the current event and previous events that
occurred in the application. By selecting a previous event, you can examine not only the state of the
application when the error occurred, but also the state of the application at earlier times. This enables
you to trace an exception back to the event where unexpected behavior began.
In order to use debugging mode, the application must be compiled with debugging symbols in the
assembly. These symbols are included whenever you compile in the Debug configuration. If you choose
the Release configuration, execution cannot stop for debugging.
In debugging mode, execution also stops when Visual Studio reaches a line in the code where you have
set a break point. This enables you to focus on an event earlier than the one that caused the exception.
You can also use a break point to ensure that the application behaves as expected when there is no
exception. When the code is halted, you can step through lines of code one-by-one to examine the state
of the application and how it changed.
Enabling Debugging in Web.Config

You cannot use debugging mode with an ASP.NET web site unless debugging is permitted in the
web.config file. This restriction applies to SharePoint sites because SharePoint is an ASP.NET Web Forms
application. To enable debugging, set the debug attribute of the <compilation> element to true.
This abbreviated web.config file shows how to enable debugging mode:
Enabling Debugging in Web.config

<configuration>
<system.web>
<compilation debug="true">
</compilation>
</system.web>
</configuration>
Best Practice: You should enable debugging only in development, testing, and staging
sites. Never enable debugging in production sites, because debugging information can help
malicious users to find out about your configuration and software. This may enable those users to
mount an effective attack against your site.
When you start a web application in debugging mode for the first time, Visual Studio may ask whether
you want to enable debugging in the web site. If you answer yes, the debug attribute is set to true for
you.
In addition to enabling debugging, you can obtain additional information about errors by disabling
custom errors in the customErrors element, and configuring SharePoint to display the full call stack for
errors by using the SafeMode element. To disable custom error pages, set the mode attribute of the
customErrors element to Off. To enable full call stack information, set the CallStack attribute of the
SafeMode element to true.
Developer Site Collection Template

SharePoint 2013 includes a new template named the Developer Site template that you can use to create
new site collections. The template creates a single top-level site with libraries that include Site Pages, Site
Assets, and Documents. There is also a link on the Quick Launch to the SharePoint Developer Center and
links on the home page to help developers learn about app development and publishing.
When you develop an app in Visual Studio 2012, you must select a debugging site based on the
Developer Site template. If you do not select such a site, you will receive the following error when you
start the app in debugging mode: "Sideloading of apps is not enabled on this site". If this situation arises,
you can resolve it by enabling the Developer Site collection feature. However, the Developer Site
collection feature is a hidden feature, so you must use PowerShell to enable it.
The following code shows how to enable the Developer site collection feature:
Enabling the Developer Feature in PowerShell

Get-SPFeature Developer | Enable-SPFeature –url http://dev.contoso.com
Debugging JavaScript Code

JavaScript is used extensively in SharePoint Apps
and may also be used in SharePoint solutions.
Debugging JavaScript differs from debugging .NET
managed code in several ways.
Minimized and Debugging JavaScript

Libraries
Code designed to be human-readable includes
spaces, return characters, and tabs that illustrate the
structure of the code. Variables often have long
names to help developers understand what they
store. The code may also contain references to
other JavaScript files to enable Visual Studio to
provide IntelliSense. These characters and names make a significant difference in the size of the code file.
In a production environment, JavaScript files should be as small as possible to ensure that they download
rapidly. This is particularly important in large JavaScript libraries such as jQuery or the core SharePoint
libraries. For each of these libraries, two versions are available:
 Development Version. This version is human-readable and includes white space and helpful variable
names. In jQuery, the development version of the library is named jquery.js. SharePoint development
libraries have the suffix .debug.js.
 Minimized Version. This version is not easy to read because white space has been removed and
variables have short, non-descriptive names. In jQuery, the minimized version of the library is named
jquery.min.js. SharePoint minimized libraries have no .debug in the suffix.
During the development, testing, and staging phases of a project, make sure that you link to the
development version of each JavaScript library. The structure and variable names in these versions make
debugging easier and make mistakes obvious.
Best Practice: Make sure all developers realize that they should switch to minimized
versions of all the JavaScript libraries just before the project is deployed. In addition, you should
bundle custom JavaScript into larger libraries to improve performance.
Visual Studio JavaScript Debugging

Visual Studio 2013 can debug JavaScript with almost all the functionality you see when you debug .NET
managed code. For example, you can set break points, investigate values by using the Immediate window,
and step through code.
Many of the JavaScript files sent to the browser are static and you can explorer them and set break points
before you start the project in debugging mode. However, sometimes JavaScript files are created
dynamically, for example by ASP.NET pages, or linked to on Internet locations such as Content Delivery
Networks (CDNs). Such JavaScript files are displayed by Visual Studio in the Solution Explorer when
debugging begins under the title Script Documents. This enables you to:
 Explore and understand dynamically generated and remote JavaScript files.
 Set break points in dynamically generated and remote JavaScript files.
 Step into code in dynamically generated and remote JavaScript files.

Internet Explorer JavaScript Debugging

Internet Explorer also includes JavaScript debugging support as part of the F12 developer tools. The Visual
Studio debugger will always take priority when it is available. Therefore, if you want to use the Internet
Explorer debugging tools, you must run the Visual Studio project without debugging. To do this, click
DEBUG and then click Start without Debugging. Alternatively, press CTRL F5.
The Internet Explorer debugger enables you to explore any of the JavaScript files linked to by the
currently loaded page and to set break points. There are Call Stack, Locals, and Watch windows that
enable you to examine the state of the application.
Demonstration: Debugging JavaScript in Visual Studio and Internet

Explorer
 Use the Visual Studio Debugger to debug JavaScript in a SharePoint app.

 Use the Internet Explorer F12 developer tools to profile the functions called in a web page.
Demonstration Steps
In the App.js file, insert a breakpoint on the call to the getTaxonomySession() function.
1. Start the app in debug mode, and trust the app.
Note: Visual Studio enters break mode at the break point you specified.
2. Point out that all the JavaScript files used by the app have been added to the Script Documents
folder. Click some script documents and examine the code within students.
3. Step into the executing code four times. Point out that the debugger steps into code in the
SP.Taxonomy.js file and then sp.runtime.debug.js file.
4. Stop debugging.
5. Start the app without debugging. Point out that the breakpoint is not hit, because the Visual Studio
debugger is not running.
6. Access the Profiler tool in the F12 developer tools.
7. Start the Profiler, refresh the page in Internet Explorer, and then stop the Profiler.
8. In the list of functions, locate the line for the loadTermStore function. Point out how long the
function took to complete.
9. Close the developer tools, Internet Explorer, and Visual Studio.

Debugging REST Calls

SharePoint cloud-hosted apps often use the
SharePoint REST API to access information in the
host web and app web. This can be for displaying
information, such as the contents of a SharePoint
list, or for modifying information, such as the
properties of an existing list item. For more
information about how to use the REST interface,
see the following article:
Understanding and Using the SharePoint

2013 REST Interface
2
When you call REST APIs, responses are returned in XML or JSON formats. These are text formats that
JavaScript code can easily de-serialize in order to create objects with easy-to-access properties, collections
and so forth. However, because these responses can be large and complex, it can be hard to diagnose
when a REST call returns something unexpected. In such circumstances, you may cause exceptions, for
example by coding against a property that has not been returned.
It is therefore helpful to be able to debug your app by examining XML and JSON responses from REST
calls.
To determine what properties to expect from a REST request, use the JavaScript Client Side Object Model
(CSOM) reference documentation. Because the JavaScript CSOM is built on the REST API, the properties
returned by a REST call match those of the corresponding object in the CSOM. For example, a request to
an URL like http://dev.contoso.com/_api/web returns the same properties as the SP.Web object in the
JavaScript CSOM.
Checking Data in Internet Explorer

One simple way to check the structure of data returned from a REST request is to disable feed reader view
and then enter the REST resource endpoint URL in Internet Explorer. For example, to examine the REST
response for a SharePoint site, enter http://yoursharepointserver/sites/mysite/_api/web in the Internet
Explorer address bar and then press Enter. Right-click the page and then click View Source to see the
XML returned in Notepad. To see this XML formatted in a clearer structure, save the file with an .XML
extension and then open the file in Internet Explorer.
This technique with Internet Explorer is helpful because Internet Explorer is always available, but on the
other hand, it is somewhat laborious and can only be used with GET requests. Other REST operations such
as PUT, POST, and DELETE cannot be examined this way.
Using the Fiddler Web Debugger

Fiddler Web Debugger is a widely used web debugging proxy owned by Telerik. It is free to download
and use. You can use Fiddler to examine any communication between a web client, including Internet
Explorer, Microsoft Office desktop applications, and web servers. Fiddler will automatically capture any
web communication and display both the request and the response it its raw state. Fiddler is also
equipped with interpreters for HTML, CSS, and other markup formats.
Because Fiddler includes interpreters for XML and JSON, it is an ideal tool to use to examine REST requests
and responses as you debug a SharePoint cloud-hosted app. To examine a request made by your app,
complete the following steps:
1. Start the app and navigate to the page, button, or action that you want to test in Internet Explorer.
2. Start Fiddler. Fiddler automatically connects to all the current Internet Explorer web server sessions.
The first session in the list is a request to check for Fiddler updates.
3. Click the button, reload the page, or initiate whatever action you wish to test in Internet Explorer.
4. When the action is complete, switch to Fiddler. You will see one session for every request and
response in the list on the left.
5. Select a session. Fiddler displays the request details in the top right and the response details in the
bottom right.
6. Select a view. For example, if the request headers specified JSON, select the JSON viewer to see the
response from the server.
You can download Fiddler from the following link.
Fiddler
Debugging Remote Events

SharePoint cloud-hosted apps can include remote
event receivers. These are methods in the remote
web code that can respond to events that happen
within SharePoint. For example, you can create
remote event receivers that execute when items are
added to a SharePoint list or when lists are added
to a host web. Remote event receivers can also
handle app lifecycle events such as app installation
and app upgrade.
Remote event receivers are .NET classes in the

remote web that implement the
IRemoteEventService interface. These are bound
to the events themselves by an Elements.xml file that is installed in the App web. When you add a remote
event receiver to your app, Visual Studio creates a WCF service in the remote web. The Elements.xml file
links to this WCF service and, when a relevant event occurs, SharePoint calls the service and sends
information about this event.
Remote Event Receivers and Remote SharePoint Servers

In earlier versions of SharePoint, developers installed SharePoint Server on their development computer in
order to run their solutions as they wrote and debugged them. In SharePoint 2013, developers do not
have to perform this installation. Instead, they can develop against a remote SharePoint server or against
SharePoint 2013 Online in Office 365™. However, this can present a challenge when you want to debug
remote event receivers in cloud-hosted SharePoint apps:
 SharePoint runs on a remote server. This is where events occur. SharePoint must be able to call the
WCF service in the remote web.
 The remote web runs in IIS Express or the Visual Studio Development Server on the developer's
computer.
In this scenario, SharePoint may not be able to reach the WCF service because it is not in the location
specified in the Element.xml file.
Debugging Remote Event Receivers

In order to solve this problem and to enable SharePoint to locate WCF services for remote events during
debugging, you can use a Windows Azure™ Service Bus. These service busses provide a secure, hosted
infrastructure that enables WCF services and web services to connect even if they are separated by
firewalls, network address translation (NAT) boundaries, DCHP dynamic IP addresses, and other
challenges.
To configure a Windows Azure Service Bus for remote event debugging, complete the following steps:
1. Register for a Windows Azure account.
2. Create a new service bus. A service bus requires you to create a unique name and select a region
close to you.
3. Copy the connection string from the properties of the new service bus.
4. In Visual Studio, right-click the SharePoint project and select Properties.
5. In the Properties windows, select the SharePoint tab.

6. Select the Enable remote event debugging checkbox.
7. Paste the connection string into the Windows Azure Service Bus connection string box.
Windows Azure Account Registration

Lesson 2
Diagnosing Faults in Deployed Apps
In a perfect world, all bugs would be identified and removed before the app is deployed to the
production environment. In practice, this is rarely achieved and complex situations, which are difficult to
properly simulate during testing, may result in users experiencing exceptions. When such exceptions
occur, it is helpful to have access to as much information about the exception as possible so that you can
diagnose the problem, code a solution, and deploy a new version as quickly as possible. In this lesson, you
will see how to arrange for an app to record much more information than you could obtain from the user.
Lesson Objectives
 Log information to the App Monitoring user interface.
 Enable the user to switch on IIS tracing to collect information about an exception.
 Add profiling packages from the NuGet package manager and use them to record an app's behavior.
Logging Errors in the App Monitoring Page

When a SharePoint site administrator installs an
app, they can access a page that displays the details
of runtime errors. This is named the App
Monitoring User Interface.
Accessing the App Monitoring User

Interface
To add the monitoring user interface for an app,
follow these steps from the host web home page:
1. In the Quick Launch, click Site Contents.

2. Find the app in the contents list. Point to the
app and then click the ellipsis in the top right
of the app's entry,
3. Click DETAILS.
Under Errors, the app monitoring user interface displays the numbers of installation errors and upgrade
errors. It also displays the number of runtime errors in the last four days. If the user clicks on the number
of runtime errors, details of each error are displayed. The following values are included:
 The exception error message.
 The time and date of the exception.
 The correlation ID.
Logging Information to the App Monitoring User Interface

You can use two static methods on the SP.Utilities.Utility class to record errors in the app monitoring
user interface:
 logCustomAppError(). Use this method to report errors from SharePoint-hosted apps.
 logCustomRemoteAppError(). Use this method to report errors from provider-hosted or auto-hosted

apps.
The following code illustrates how to use the logCustomAppError() method to log an exception in a
SharePoint-hosted app:
Logging Errors in a SharePoint-Hosted App

//Obtain the client context
try
{
//Place the operation that may cause an exception in a try block
}
catch (Exception e)
{
//Log the exception in the corresponding catch block
SP.Utilities.Utility.logCustomAppError(context, "The operation caused an exception.
The details were: "
+ e.Message);
}
IIS Tracing
The ASP.NET processing pipeline includes a tracing
facility that can record rich information about every
page. This information includes pages that load and
execute without exceptions, as well as pages that
cause problems. Developers can also use the
System.Diagnostics.Trace.Write() method to
record custom information. You can access the
trace logs through the trace.axd file.
ASP.NET tracing can significantly slow the

performance of a SharePoint app because ASP.NET
must record every operation. For this reason, you
should ensure that tracing is disabled by default.
When problems arise, you can provide a user or administrator with a way to enable tracing. When they
retry the action with tracing enabled, the trace logs can provide the rich information necessary to
diagnose the fault.
Building Diagnostic Tools

To enable a user to switch tracing on and off, complete the tasks below.
Start by adding a <trace> element to the web.config file. The following code illustrates how to do this:
Configure Tracing in Web.config

<system.web>
<trace enabled="false" pageOutput="false" requestLimit="100" localOnly="false"
traceMode="SortByTime" mostRecent="true" writeToDiagnosticsTrace="true" />
</system.web>
Notice that the above XML disables tracing by default, but configures values such as the trace mode and
the request limit.
Next, create code that enables tracing. The following code, for example, may run when the user clicks an
Enable Tracing button in the app user interface:
Enabling Tracing in C#
//Get the current ASP.NET config
Configuration config = WebConfigurationManager.OpenWebConfiguration("~");
//Get the tracing element of web.config

TraceSection traceElement = (TraceSection)config.GetSection("system.web/trace");
//Enable tracing and save the changes

traceElement.Enabled = true;
config.Save();
Best Practice: Make sure to provide the user with a second button or other method to
disable tracing when diagnostic information has been recorded.
To enable the user to view trace logs, link to the trace.axd page, as in the following HTML example:
Linking to trace.axd
<a href="~/trace.axd" target="traceinfo">View The Trace Log</a>
If a user experiences a persistent problem, have them complete the following steps to provide full
diagnostic information:
1. Enable tracing.
2. Repeat the action that generates the exception or unexpected behavior.
3. Disable tracing.
4. Click the link to the trace log.
5. Copy and paste the trace log into an email or other communication and send it to you.
Using NuGet Logging Packages

NuGet is a package management tool that is built
into Visual Studio 2012 and other Microsoft
development tools such as WebMatrix. Using
NuGet, you can add a huge range of packages to a
Visual Studio project and then use them in your
code. In this topic, you will learn more about NuGet
and focus on two NuGet packages that you can use
to log errors at runtime in the production
environment: ELMAH and MiniProfiler.
The NuGet Package Manager

NuGet is a package manager for the Microsoft
development platform. It consists of:
 NuGet Client Tools. The client tools enable developers to both create NuGet packages and install
NuGet packages to use them in a Visual Studio project.
 NuGet Gallery. The gallery is a repository of third-party NuGet packages. There are more than 15,000
packages currently available in the library for many purposes.
A new get package is a single file with a .nupkg extension. All files that the package adds to a Visual
Studio project are bundled into this file, together with a manifest file that Visual Studio uses to install or
remove the package.
ELMAH
ELMAH is a popular error-logging package that you can add to your app to record unhandled exceptions.
ELMAH stands for Error Logging Modules and Handlers, and it consists of ASP.NET modules and handlers
that intercept exceptions. ELMAH does not modify error handling in your app; users see either a standard
ASP.NET error page or a custom page (if you have implemented one). ELMAH records exception numbers,
messages, and other details to create a log that you can use to assess the health of your app and to
diagnose any faults or bugs.
ELMAH intercepts errors by using the ASP.NET HttpApplication.Error event. Any errors that are caught
and gracefully handled, for example in catch blocks, do not reach ELMAH. If the code calls the
Server.ClearError() method, the exception does not reach ELMAH. ELMAH can only record unhandled
exceptions.
You configure ELMAH in the web.config file, and you can instruct it to log exception information to a SQL
Server® database or other locations.
To view the exception logs, ELMAH adds the /elmah/default.aspx page to your project. This displays a list
of all exceptions. For each exception you can view a details page that shows trace information, error
numbers, and messages. Administrators and developers can also subscribe to an RSS feed that alerts them
about new exceptions as they arise. You can read more information about ELMAH and browse the project
WIKI at the following location:
ELMAH Project
http:/go.microsoft.com/fwlink/?LinkId=321983
MiniProfiler
MiniProfiler is a NuGet package that can profile the behavior and performance of an ASP.NET application,
including a SharePoint cloud-hosted app. Because you have granular control over which operations are
recorded, you can use MiniProfiler in a production environment, where other profiling packages may
negatively affect performance. The information MiniProfiler displays can include all the methods called to
render a page and their timings. This information can be extremely helpful in diagnosing bugs in
deployed ASP.NET apps.
An important advantage of MiniProfiler is that you can run checks against the ASP.NET request before
starting the profiler. For example, you could run the profiler only when the request is from a local browser,
when the request is from an administrator, or when the request includes a certain parameter in the query
string.
In the following ASP.NET example, MiniProfiler is enabled only when the query string includes
"Profile=true":
Enabling the MiniProfiler

protected void Application_BeginRequest()
{
//Check the query string
if (Request.QueryString["Profile"] == "true")
{
MiniProfiler.Start();
}
}
protected void Application_EndRequest()

{
//Make sure you stop the profiler as early as possible to reduce the performance
impact
MiniProfiler.Stop();
}
When MiniProfiler is enabled, it adds a link to each profiled page that displays performance information.
You can find more information about using MiniProfiler at the following location:
MiniProfiler
The Developer Dashboard

Capturing and analyzing network traffic can help
you diagnose a range of problems, but it does not
provide any insight into how SharePoint generates
and renders specific pages. To investigate more
complex issues, you can use the SharePoint
Developer Dashboard to provide detailed insights
into the page build process and code execution
behind individual page requests.
The Developer Dashboard was introduced in

SharePoint 2010, but it has been completely
redesigned for SharePoint 2013. It now runs in a
separate window so that it does not interfere with
the SharePoint page. It uses a dedicated Windows Communication Foundation (WCF) service,
Diagnosticsdata.svc, to retrieve results. At the top level, the Developer Dashboard provides a breakdown
of individual requests in a manner similar to client-side tracing tools. For each of these individual requests,
you can view the following additional information:
 Server info. This tab displays general information about the request, such as the start time, duration,
CPU time, memory, and correlation ID associated with the request.
 Scopes. This tab provides a breakdown of how long the request spends at each point in the call stack.
 SQL. This tab provides details of any database calls made during the processing of the request.
 SPRequests. This tab provides details of any background requests that occurred in addition to the
page request.
 Asserts. This tab identifies any assert calls made during the request. Assert calls are used by
developers to write details of unexpected conditions to an output window.
 Service Calls. This tab provides details of any calls to web services made during the request.
 ULS. This tab contains all the trace log entries associated with the current request.
 Cache Calls. This tab provides details of any cache calls made during the request.
Note: In addition to the base functionality, you can now extend the developer dashboard
by injecting custom JavaScript code into the developer dashboard.
To access the developer dashboard, you must first enable it. You use PowerShell to enable the developer
dashboard on a farm-wide basis.
The following code sample shows how to enable the developer dashboard for a SharePoint farm by using
PowerShell cmdlets:
Enabling the Developer Dashboard

$contentService = [Microsoft.SharePoint.Administration.SPWebService]::ContentService
$settings = $contentService.DeveloperDashboardSettings
$settings.DisplayLevel = "On"
$settings.Update()
After you have enabled the developer dashboard, you can open it from any SharePoint page. SharePoint
will add a Launch the Developer Dashboard button to the ribbon on each page while the dashboard is
enabled.
The following code sample shows how to disable the developer dashboard for a SharePoint farm by using
PowerShell cmdlets:
Disabling the Developer Dashboard

$contentService = [Microsoft.SharePoint.Administration.SPWebService]::ContentService
$settings = $contentService.DeveloperDashboardSettings
$settings.DisplayLevel = "Off"
$settings.Update()
Lesson 3
Testing Performance and Scalability
The SharePoint app architecture is by its nature highly scalable because much of the code runs on the
client side, as JavaScript executed by the browser. Such a design reduces the likelihood of contention for
server memory and processing resources. However, even with such a scalable architecture, your code may
still be slow to execute for many reasons that are not obvious at design time. In this lesson, you will learn
how to investigate the behavior and performance of a SharePoint app, remove bottlenecks, and assess the
limits on its scalability.
Lesson Objectives
 List the boundary and supported limits for scaling apps in SharePoint 2013.
 Choose a tool for testing the performance and scalability of an app.

 Use a profiler to investigate the relative performance of different components and procedures in an
app.
 Use Visual Studio Ultimate to perform stress tests on your app.
SharePoint App Boundary and Supported Limits

Microsoft publishes a number of limits on the
scalability of SharePoint apps, of two types:
 Boundary Limits. These are hard limits that

cannot be exceeded.
 Supported Limits. You can exceed these limits,

but you should expect some degradation in
performance or some other negative impact.
The published limits are much larger than the

values that a typical organization is likely to reach,
but you should be aware of these limits for very
large or unusual situations.
Maximum
Limit Type Notes
Value
Number of apps in the Boundary 2,000 If you exceed this number of apps, you
Manage Licenses page can manage licenses in the Site Contents
page of a site where a user has installed
the app.
Number of app Supported 1,000,000 If you purchase more than 1,000,000 total
Licenses in a single licenses for all the apps in a tenancy, you
tenancy may cause a severe reduction in
performance.
Number of apps Boundary 240 If there are more than 240 apps available
displayed in the Add an for installation in a site, a message shows
App page that you can use the search tool to locate
an app for installation.
Maximum
Limit Type Notes
Value
Number of managers Boundary 30 This limit cannot be exceeded.

for each app license
Number of app licenses Boundary 2,000 If managers assign more than 2,000 app
that a single user can licenses to a single SharePoint user, that
view user will not see any apps in the Add an
App view. Instead the user will be directed
to search for apps.
Number of apps that a Boundary 500 If there are more than 500 apps available
user can see in the for a user to install, that user will not see
corporate catalog any apps in the corporate catalog. Instead
the user will be directed to search for
apps.
The above limits generally restrict the scalability of apps, but note that none of these limits affects a single
app. If you design an app or a set of apps carefully, you should not reach the limits described or cause any
of your customers to reach these limits.
To learn about all the published boundaries and supported limits for SharePoint 2013, see the following
location:
Software boundaries and limits for SharePoint 2013

Performance Testing Tools

You can use the following tools to obtain detailed
performance information about a SharePoint app.
Internet Explorer Developer Tools

Press F12 in Internet Explorer to access the
developer tools. These tools are designed to help
any web developer analyze, troubleshoot, and
profile the HTML, CSS, and JavaScript code in the
current web page. The developer tools are pinned
to the lower section of the browser by default, but
you can unpin the tools for a larger view.
For the purposes of analyzing performance, two tools are especially helpful:
 Profiler. To use the Profiler tool, click Start profiling and then refresh the page, click a button, or use
some other method to trigger the action you want to investigate. When the action is complete, click
Stop profiling. The view shows a list of every JavaScript function that was called while you were
profiling. For each function, you can also see how many times it executed and the time it took to
complete. You can use these timings to spot slow functions.
 Network. To use the Network tool, click Start capturing and then refresh the page, click a button, or
use some other method to trigger the action you want to investigate. When the action is complete,
click Stop capturing. The view shows a list of every network call made while you were capturing. This
includes requests for HTML pages and CSS style sheets, images and other files, and JavaScript calls
(for example, calls to web services). For each request, you can see the URL, HTTP method, result code,
and type of content. You can also see how long the request took to receive a response. The Timings
column shows how long it took to receive all the response data.
Fiddler
You have already seen that the Fiddler web debugging tool can help to investigate an app's REST calls
and XML or JSON responses. It also has features that can be used to profile app performance and spot
bottlenecks. These features include:
 The Statistics Tab. This tab shows summary statistics for all the selected sessions. This summary
information includes the total number of web requests, the number of bytes sent and received,
timings, DNS lookup performance, and response codes.
 Custom Rules. In Fiddler, rules are used to highlight sessions that match certain criteria. You can
create custom rules to, for example, display sessions in red with large responses. Such sessions may
result in slow page load times.
 The Timeline. The timeline shows the start time and duration of every selected session. The sessions
are shown in a waterfall display with time increasing to the right. This display makes slow sessions
obvious, and also highlights closed connections and instances where connection limits prevented
sessions from starting.
Note: The performance analysis tools in Internet Explorer and Fiddler are designed to work
with HTTP, HTML, CSS, and JavaScript. They cannot profile or analyze server-side .NET managed
code such as C# code in ASP.NET Web Forms in a cloud-hosted app. To analyze server-side code,
you must use Visual Studio.
Performance Tools in Visual Studio

Visual Studio includes a range of tools to help you measure and optimize the performance of any
solution, including SharePoint apps. Both client-side and server-side code can be analyzed. The tools
include:
 The Profiling Tools Performance Wizard. The performance wizard is used to configure profiling
sessions. A profiling session specifies a set of tests, each of which collects a different type of
information about the performance of the app while it runs in debugging mode.
 Command Line Profiling Tools. The command line profiling tools enable you to configure profiling
sessions by issuing commands at the prompt. You can also create a script that configures profiling.
 Performance Explorer. After a profiling session has been run, reports are displayed in the Performance
Explorer window.
 Web Performance and Load Tests. Web Performance and Load Tests are a set of tools designed to
enable developers to test how their app handles realistic loads and stress tests. You can record a set
of user actions and then replay those actions many times in order to simulate the kind of load that
may occur in the production environment.
Note: Web Performance and Load Tests is a set of tools that is only available in Visual
Studio Ultimate edition.
Profiling an App
In application development, profiling is the process
of observing and recording the performance of a
solution as it runs. You can perform profiling at
every stage of development, but it is often done
late in a project, as an application approaches
completion. Profiling ensures that the application
behaves as designed, has optimal performance, and
responds to users as quickly as possible. You can
use profiling to identify problems such as the
following:
 Hotspots. Hotspots are segments of code that

are very frequently called during execution.
You may be able to improve performance greatly by increasing the execution speed of hotspots or by
reducing the number of times they are called.
 Bottlenecks. Bottlenecks are segments of code that limit the performance of the application as a
whole. By identifying bottlenecks, you determine where optimizations make the most difference to
the performance experienced by the user.
 Unintended Calls. When you use many APIs or multiple JavaScript libraries, it can be difficult to fully
understand all method calls as you write the code. By profiling the application, you can observe all
method calls and diagnose those that are unnecessary and can be improved by selecting other
methods.
Profiling Methods
In Visual Studio, to profile an application such as a SharePoint app, you first create and configure a
profiling session. You can then run the session and view reports that show how the application behaved.
When you configure the profiling session, you specify the aspects of behavior that interest you. You can
select from the following profiling methods:
 Sampling. This method interrupts the CPU at fixed intervals and collects information about the
current call stack. This method is useful for initial investigations and for observing the load your app
places on the CPU. The method has a relatively small impact on the performance of the app.
 Instrumentation. This method adds code into your app's binary files to collect detailed timing
information for each function call. This method is particularly useful for identifying bottlenecks.
 Concurrency. This method collects information about multiple threads in the app and how they
contend for resources such as CPU time. Contention is a common cause of bottlenecks because
threads are forced to wait for access to memory or processing time.
 .NET Memory. This method interrupts the CPU whenever a .NET object is assigned to memory. The
method also interrupts the CPU during garbage collection, when unused objects are removed from
memory. You can use this method to study memory use in detail.
 Tier Interaction. In a SharePoint app, you can use this method to collect information about the calls
between ASP.NET server-side code and the database.
Profiling Process
To profile an app by using Visual Studio, you must complete the following steps:
 Configure a Profiling Session. You can use the Performance Wizard or the command line profiling
tools to configure a session. You must specify the profiling methods that you want to execute and
select the binary files that you want to target.
 Launch the Profiling Session and Perform Actions. When you start the profiling session, Visual Studio
compiles and launches the app. You must takes actions such as clicking links, buttons, uploading
documents, and taking whatever other actions you want to test. When you close the app, Visual
Studio saves the profiling data in a Sample Profiling Report.
 Investigate the Profiled Data. You can view summary and detailed information from the profiling
session in the Performance Explorer window.
Data in Performance Explorer may help you to identify hotspots, bottlenecks, and other performance
problems in your code. It is important to take an iterative approach. That is, after you have edited the app
to remove a bottleneck, rerun the performance session to observe the difference you have made.
Stress Testing Apps

After using profiling to identify and remove
bottlenecks, you have an app with optimized
performance. If you intend to deploy this app into a
large organization or if you intend to publish this
app in the Office Store, you should quantify the
hardware resources that are required to run the app
for large numbers of users. Such information can be
used by administrators to architect hardware
resources on which to host your app and to ensure
that a deployment can cope with the expected
demand.
Stress testing an app is a method by which you can

quantify hardware resources. In stress testing, you simulate the load you expect from a large number of
users and measure the response of your app. By increasing the load until the app reaches its limits, you
can make recommendations for large-scale deployments.
Stress testing requires many assumptions about users. For example, it is difficult to precisely predict the
actions a user will take in a typical session. For this reason, you should regard stress-testing results as
approximations of real-world scenarios. Nevertheless, stress testing results are extremely useful, especially
before you have any real-world deployments of you app to measure.
Stress Testing Process

Visual Studio 2013 Ultimate edition includes the Web Performance and Load Tests toolset. You can use
these to record typical user sessions, then run load tests during which multiple repetitions of the recorded
sessions are simulated. After each load test, you can examine statistics that summarize the behavior of the
app under stress and enable you to determine scalability limits.
The stress testing process involves the following steps:
1. Record web performance tests. A web performance test is a recorded set of actions. Usually such a test
records the steps a single user takes to perform a simple task. For example, you may record a web
performance test in which a user creates a new SharePoint item by using your app. You should record
web performance tests for each common function of an app.
2. Configure a load test. During a load test, one or more web performance tests are executed by Visual
Studio multiple times simultaneously in order to simulate the load generated by many concurrent
users in a real deployment. To configure load tests, you choose the web performance tests to run and
specify the number of users to simulate, together with other parameters.
3. Execute a load test. When your load test configuration is complete, you can use Visual Studio to run
the simulation and execute the web performance tests.
4. Analyze load test results. Visual Studio includes the Web Performance Test Results Viewer, which you
can use to view statistics about a single instance of a web performance test, whether that test was run
individually or as part of a load test. To analyze data that summarizes the load test as a whole, use the
Load Test Analyzer tool
Handling Dynamic Parameters

One challenge to running web performance tests is the presence of dynamic parameters in almost all
SharePoint requests. A dynamic parameter is a parameter whose value alters every time the app is run. For
example, the session ID is unique to every user session. Similarly, the username is different for every user
that connects to your app. If web performance tests request identical values for dynamic parameters every
time they run, errors occur and the tests do not simulate the real world. To avoid this problem, Visual
Studio can modify dynamic parameter values automatically.
Validation and Extraction Rules

In a load test, many web performance tests are executed simultaneously. It can be difficult to be sure that
each web performance test is running as expected and simulating a user action accurately. For example, if
a test instance encounters an exception, the load it places on the SharePoint server is unlikely to match
the load placed on the server by a user completing the simulated operation successfully. Results in the
Load Test Analyzer may not draw attention to this exception.
In order to increase your confidence in the accuracy of web performance tests, you can define two types
of rules:
 Validation Rules. Validation rules check the existence of text, HTML tags, and HTML attributes in the
page returned by a web request. For example, when your web performance test requests a SharePoint
item, you could define a validation rule to check that the returned page included a <div> tag with
the ID "Title".
 Extraction Rules. Extraction rules check that values are present in form fields and query strings
parameters. For example, you could define an extraction rule that checked an item's GUID.
For more information about stress testing SharePoint apps by using Visual Studio Ultimate, see:
Web Performance and Load Testing SharePoint 2010 and 2013 Applications
Discussion: Choosing a Performance Tool

Discuss the following scenarios with the class. In
each case, decide which tool you could use to
achieve the stated aims:
Preparation for Deployment

You have a complete SharePoint provider-hosted
app that you plan to publish in the Office Store.
You have a list of 10 partner organizations that are
committed to buying your app as soon as it
becomes available. These organizations have an
approximate total of 50,000 users. How can you
ensure that the server hardware that hosts the
remote web for the app can cope with the load
placed upon it?
Identification of a Bug
You have deployed your provider-hosted app. All is running smoothly, but occasionally users complain of
an error message. You are unable to replicate this error message. How can you obtain more information
about the error?
Optimization of a Procedure
You add JavaScript code to your provider-hosted app that calls a third-party web service to obtain
industry news stories. You notice a reduction in performance of the app. You want to determine whether
the slow performance is due to your new code or to some other problem.
Lab: Enabling ASP.NET Tracing

Scenario
Occasional page errors in the Mileage Recorder app have proved difficult to replicate and fix in the
development environment. You have been asked to enable ASP.NET tracing to ensure that users can
generate more diagnostic information when problems arise.
Objectives
 Enable tracing in the web.config file.
 Create a diagnostic tools page on which users can enable and disable tracing.
 Enable tracing page output and view the trace logs.
Lab Setup

Exercise 1: Adding a Diagnostics Page to a SharePoint App

Scenario
In this exercise, you will add a page where users can enable and disable ASP.NET tracing of the Mileage
Recorder SharePoint app. The app is an auto-hosted app built by using ASP.NET MVC. To create the new
page, you must add a new MVC action to the Home controller and create a new view. The app uses the
SharePoint Chrome Control, and you will configure this to provide a link to the new Diagnostics page.
1. Add a Diagnostics Action to the Home Controller
2. Add a Diagnostics View
3. Link to the Diagnostics View
4. Test the Diagnostic View
 Task 1: Add a Diagnostics Action to the Home Controller

1. Open the following solution: E:\Labfiles\Starter\MileageRecorder\MileageRecorder.sln
2. Add a new method to the HomeController class in the Controllers\HomeController.cs code file.
o Scope: public
o Return type: ActionResult
o Name: Diagnostics
3. In the new Diagnostics method, return a View named Diagnostics.
 Task 2: Add a Diagnostics View

1. Add a new view to the MileageRecorderRemoteWeb project. Use the following information:
o Folder: Views/Home
o View name: Diagnostics
o View engine: Razor
o Do not create a strongly typed view
o Do not create a partial view
o Use the layout specified in _ViewStart.cshtml
 Task 3: Link to the Diagnostics View

1. Open the App.js script file for editing and change the appTitle to Contoso Mileage Recorder.
2. Add a property to the options object named settingsLinks.

3. In the settingsLinks property object, set the linkUrl property to ../Home/Diagnostics?, and then
append all of the URL that appears after the ? character.
4. In the settingsLinks property object, set the displayName property to Diagnostics.
 Task 4: Test the Diagnostic View

1. Start the app in debugging mode, trust the new certificate, and confirm that you want to install the
certificate.
2. Trust the app.
3. In the Settings menu, click the Diagnostics link.
Note: The app displays the Diagnostics view, but there is no content other than the title.
4. Stop debugging the app.
Results: A SharePoint auto-hosted app with a new Diagnostics page.
Exercise 2: Configuring ASP.NET Tracing

Scenario
Now that you have created the Diagnostics page, you will add code that enables users to switch ASP.NET
tracing on and off. You will also provide user interface elements and a link to the trace.axd page to
investigate the trace.
1. Edit Web.config
2. Display Tracing Status
3. Enable Users to Toggle Tracing
4. Build the Diagnostics User Interface
 Task 1: Edit Web.config

1. Open the Web.config file in the root folder of the MileageRecorderRemoteWeb project.
2. Insert a new <trace> element within the <system.web> element. Use the following information:
o Enabled: false
o Local Only: false
o Most Recent: true
o Page Output: false
o Request Limit: 100
o Trace Mode: SortByTime
o Write to Diagnostics Trace: true

4. Close the Web.config file.
 Task 2: Display Tracing Status

1. In the Diagnostics method of the HomeController class, use the
WebConfigurationManager.OpenWebConfiguration() method to access the root web.config file.
Store the returned file in a new Configuration object named currentConfig.
2. From the currentConfig object, get the trace section and store it in a new TraceSection object
named traceSection.
3. Store the value of the traceSection.Enabled property in a new ViewBag property named
TracingStatus.
4. In the Diagnostics.cshtml view, add a Razor if…else code block that checks the
ViewBag.TracingStatus property.
5. If ViewBag.TracingStatus is true, display a <p> element that tells the user that tracing is enabled.
6. If ViewBag.TracingStatus is false, display a <p> element that tells the user that tracing is disabled.
 Task 3: Enable Users to Toggle Tracing

1. Add a new action to the HomeController class. Use the following information:
o Scope: public
o Return type: ActionResult
o Name: ToggleTracing
o Parameter: a Boolean variable named switchOn
2. In the new ToggleTracing method, use the WebConfigurationManager.OpenWebConfiguration()

method to access the root web.config file. Store the returned file in a new Configuration object
named currentConfig.
3. From the currentConfig object, get the trace section and store it in a new TraceSection object
named traceSection.
4. Set the traceSection.Enabled property to the value of the switchOn parameter.
5. Save the changes to the currentConfig object.
6. Store the value of the switchOn property in a new ViewBag property named TracingStatus.
7. Return the Diagnostics view.
 Task 4: Build the Diagnostics User Interface

1. In the Diagnostics.cshtml view, if the tracing status is enabled, render a link that enables users to
switch off tracing. Use the following information:
o Helper: Html.ActionLink()
o Link Text: Switch Off Tracing

o Action Name: ToggleTracing
o Controller: Home
o switchOn: false
o SPHostUrl: Pass the value of the SPHostUrl query string parameter.
o SPAppWebUrl: Pass the value of the SPAppWebUrl parameter.
2. After the Switch Off Tracing link, render a link to the ~/trace.axd page.
3. If the tracing status is disabled, render a link that enables users to switch on tracing. Use the following
information:
o Helper: Html.ActionLink()
o Link Text: Switch On Tracing
o Action Name: ToggleTracing
o Controller: Home
o switchOn: true
o SPHostUrl: Pass the value of the SPHostUrl query string parameter.
o SPAppWebUrl: Pass the value of the SPAppWebUrl parameter.
Results: A SharePoint auto-hosted app with tracing facilities.
Exercise 3: Using Trace Logs

Scenario
In this exercise, you will test the code and user interface elements you have built by enabling tracing and
viewing the trace logs.
1. Enable Tracing
2. Make Test Requests
3. View Trace Logs
 Task 1: Enable Tracing

1. Start the app in debugging mode.
2. On the Diagnostics page, enable tracing.
 Task 2: Make Test Requests

1. Browse to the Contoso Mileage Recorder home page.
2. Create a new mileage claim. Use the following information:
o Destination: New York
o Reason for Trip: Business Meeting.
o Miles: 100
o Engine Size: 1600
 Task 3: View Trace Logs

1. From the Diagnostics page, view the trace logs.
2. For the GET request for the Diagnostics page, record the value of the SPAppWebUrl query string
parameter.
3. For the POST request for the MileageClaim/Create address, record the value of the ReasonForTrip
parameter.
4. Switch off tracing.
Results: A SharePoint auto-hosted app in which users can enable tracing and view tracing logs to supply
information about bugs and other issues.
Question: In Exercise 2, Task 1, you added a new <trace> element to the web.config file
with the enabled attribute set to false. Why is it necessary to create this element, when code
in the ToggleTracing action sets the enabled attribute to true?
Question: What are the consequences of leaving tracing enabled after you have diagnosed a
bug?

In this module, you have seen how to debug an app of a SharePoint solution during the development
phase of a project. You have also seen how you can collect information about any issues that arise after
deployment when an app is in the production environment. Finally, you learned how to measure the
performance of an app to ensure that it responds to users as rapidly as possible.
Best Practice: Use debugging JavaScript libraries when you want to browse and step
through the code in those libraries. For production environments, switch to minimized JavaScript
libraries to ensure that the app downloads to the browser as fast as possible.
Best Practice: If you use ASP.NET Tracing or MiniProfiler to investigate a problem in a

deployed app, make sure you disable those tools as soon as you have the information you
require. These tools are likely to impact performance because of the extra work they must do to
record app behavior
Common Issues and Troubleshooting Tips

Common Issue Troubleshooting Tip
When you try to start an app in debugging

mode, you receive the error "Sideloading
of apps is not enabled on this site".
Review Question(s)
Question: You want make recommendations for the server hardware necessary to run a
SharePoint remote-hosted app. You expect several thousand concurrent users at peak times.
Should you use profiling or stress testing to determine appropriate hardware?
Statement Answer
True or False: The ELMAH NuGet package

can profile the behavior of JavaScript in
SharePoint Apps.
Course Evaluation
Your evaluation of this course will help Microsoft understand the quality of your learning experience.
Please work with your training provider to access the course evaluation form.
Microsoft will keep your answers to this survey private and confidential and will use your responses to
improve your future learning experience. Your open and honest feedback is valuable and appreciated.
L1-1
Module 1: Creating Robust and Efficient Apps for SharePoint

Lab: Monitoring SharePoint Health Scores
Exercise 1: Creating and Deploying an App Part
 Task 1: Create a New App for SharePoint
3. On the Windows Start page, type Visual Studio, and then click Visual Studio 2012.
4. On the Visual Studio Start Page, click New Project.
5. In the New Project dialog box, in the navigation pane, expand Visual C#, expand
Office/SharePoint, and then click Apps.
6. In the center pane, click App for SharePoint 2013.
7. In the Name box, type SharePointHealthScores.
8. In the Location box, type E:\Labfiles\Starter, and then click OK.
9. In the New app for SharePoint dialog box, under What is the name of your app for SharePoint,
type SharePoint Health Scores.
10. Under What SharePoint site do you want to use for debugging your app, type
http://dev.contoso.com.
11. In the How do you want to host your app for SharePoint list, click SharePoint-hosted, and then
click Finish.
 Task 2: Add an App Part

1. In Solution Explorer, right-click the SharePointHealthScores project node, point to Add, and then
click New Item.
2. In the Add New Item - SharePointHealthScores dialog box, click Client Web Part (Host Web).
3. In the Name box, type HealthScoresWebPart, and then click Add.
4. In the Create Client Web Part dialog box, ensure Create a new client web part page is selected,
and then click Finish.
5. In Solution Explorer, under HealthScoresWebPart, double-click Elements.xml.
6. In the ClientWebPart element, change the value of the Title attribute to SharePoint Health Scores.
7. Change the value of the Description attribute to Displays the current health score for the
SharePoint web application.
8. Change the value of the DefaultHeight attribute to 120.
9. Click Save All, and then close the Elements.xml file.
 Task 3: Add Support for jQuery UI

1. In Solution Explorer, right-click Scripts, point to Add, and then click Existing Item.
2. In the Add Existing Item - SharePointHealthScores dialog box, browse to

E:\Labfiles\Starter\Scripts, click jquery-ui.js, and then click Add.
L1-2 Developing Microsoft SharePoint Server 2013 Advanced Solutions
3. In Solution Explorer, right-click the SharePointHealthScores project node, point to Add, and then
click New Item.
4. In the Add New Item - SharePointHealthScores dialog box, click Module.
5. In the Name box, type SiteAssets, and then click Add.
6. In Solution Explorer, under SiteAssets, right-click Sample.txt, and then click Delete.
7. In the Microsoft Visual Studio dialog box, click OK.
8. In Solution Explorer, right-click SiteAssets, point to Add, and then click Existing Item.
9. In the Add Existing Item - SharePointHealthScores dialog box, browse to E:\Labfiles\Starter\CSS,

click jquery-ui.css, and then click Add.
10. In Solution Explorer, right-click SiteAssets, point to Add, and then click New Folder.
11. Type Images, and then press Enter.

12. In Solution Explorer, right-click Images, point to Add, and then click Existing Item.
13. In the Add Existing Item - SharePointHealthScores dialog box, browse to

E:\Labfiles\Starter\CSS\Images, select all the files in the folder, and then click Add.
 Task 4: Create the User Interface

1. In Solution Explorer, expand Pages, and then double-click HealthScoresWebPart.aspx.
2. Immediately below the title element, on a new line, add the following code:
<link rel="stylesheet" href="../SiteAssets/jquery-ui.css" />
3. Locate the following line of code:
<script type="text/javascript" src="../Scripts/jquery-1.7.1.min.js"></script>
4. Immediately below the code you just located, on a new line, add the following code:
<script type="text/javascript" src="../Scripts/jquery-ui.js"></script>
5. Within the body element, on a new line, add the following code:
<p id="healthPara">Click Start Polling to poll the server for health scores.</p>
<div id="healthBar"></div>
<br />
<button>Start Polling</button>
<button>Stop Polling</button>
6. Click Save All.
 Task 5: Add a Custom Script File

1. In Solution Explorer, right-click Scripts, point to Add, and then click New Item.
2. In the Add New Item - SharePointHealthScores dialog box, in the navigation pane, under Visual
C# Items, click Web.
3. In the center pane, click JavaScript File.
4. In the Name box, type HealthScores.js, and then click Add.
5. In the HealthScores.js file, add the following code:
'use strict';
L1-3
$('button').button();
$('#healthBar').progressbar({
max: 10,
value: 5
});
$('#healthPara').text("Current health score: 5");
});
Note: The code you just added displays a progress bar with a static value. This enables
you to ensure that your app part is configured correctly before you add custom logic.
7. Click Save All.
8. Switch to the HealthScoresWebPart.aspx page.
9. Immediately below the final closing script tag, on a new line, add the following code:
<script type="text/javascript" src="../Scripts/HealthScores.js"></script>
10. Click Save All.

4. On the Contoso Development Site home page, on the ribbon, click EDIT.
5. On the Get started with Apps for Office and SharePoint web part, click REMOVE THIS.
6. Click inside the content area above the Apps in Testing web part, and then on the ribbon, on the
INSERT tab, click App Part.
7. In the Parts list, click SharePoint Health Scores, and then click Add.
8. On the ribbon, click SAVE.
9. Verify that the SharePoint Health Scores web part displays:
a. A paragraph with the text Current health score: 5.
b. A progress bar with a gray fill color to the midway point.
Results: After completing this exercise, you should have created, configured, and deployed an app part.
Exercise 2: Working with Server Health Scores

 Task 1: Use the Revealing Module Pattern to Structure the JavaScript code
1. In Solution Explorer, under Scripts, double-click HealthScores.js.
2. Delete everything except the following line:
'use strict';
Contoso.HealthScores = function () {
}();
5. On a new line between the curly braces you just added, add the following code:
$('button').button();
var healthScore;
var pollInterval;
6. Immediately below the code you just added, on a new line, add the following code:
var getHealthScore = function () {

};
var startPolling = function () {
};
var stopPolling = function () {
};
return {
StartPolling : startPolling,
StopPolling : stopPolling
}
7. Click Save All.
 Task 2: Add Health Score Polling Functionality

1. In the HealthScores.js file, modify the getHealthScore function to resemble the following code:
var getHealthScore = function () {

$.ajax({
type: "HEAD",
url: "_layouts/15/blank.htm",
success: function (data, status, xhr) {
healthScore = xhr.getResponseHeader("X-SharePointHealthScore");
$('#healthPara').text("Server health score: " + healthScore);
$('#healthBar').progressbar("option", "value", parseInt(healthScore));
}
});
};
L1-5
2. Modify the startPolling function to resemble the following code:
var startPolling = function () {

$('#healthBar').progressbar({
max: 10,
value: 0
});
getHealthScore();
pollInterval = setInterval(getHealthScore, 5000);
};
3. Modify the stopPolling function to resemble the following code:
var stopPolling = function () {

clearInterval(pollInterval);
$('healthPara').text("Click Start Polling to poll the server for health scores.");
$('#healthBar').progressbar("destroy");
};
4. Click Save All.
 Task 3: Connect the Start Polling and Stop Polling buttons

1. In Solution Explorer, under Pages, double-click HealthScoresWebPart.aspx.
2. Locate the button element with a value of Start Polling, and edit the element as follows:
<button onclick="Contoso.HealthScores.StartPolling();">Start Polling</button>
3. Locate the button element with a value of Stop Polling, and edit the element as follows:
<button onclick="Contoso.HealthScores.StopPolling();">Stop Polling</button>
4. Click Save All.

4. On the Contoso Development Site home page, on the SharePoint Health Scores web part, click
Start Polling.
5. Verify that the web part displays a server health score and a progress bar indicator.
Note: The health score is likely to remain static at 0 at this point, as the server is under very little
load.
6. Without closing Internet Explorer, open a File Explorer window and browse to E:\Labfiles\Starter.
7. Right-click LoadWebServer.ps1, and then click Run with PowerShell.
Note: If the PowerShell window displays an Execution Policy Change message, type Y,
and then press Enter.
8. Switch back to Internet Explorer, and verify that the web part displays an increased server health
score.
Note: It may take several seconds before the increase in load is reflected by the health score.
9. Click Stop Polling, and verify that the progress bar is removed from the web part.
Results: After completing this exercise, you should have configured an app part to poll the server for
health scores.
L2-1
Module 2: Developing Managed Metadata Solutions

Lab A: Developing Managed Metadata
Solutions (Part 1)
Exercise 1: Creating and Configuring the Corporate Structure App
 Task 1: Create a New SharePoint-Hosted App
3. On the Windows Start page, click Visual Studio 2012.
4. On the FILE menu, point to New, and then click Project.
5. In the New Project dialog box, under Templates, expand Visual C#, expand Office/SharePoint, and
then click Apps.
6. In the list of templates, click App for SharePoint 2013.
7. In the Name box, type CorporateStructureApp.
8. Next to the Location box, click Browse.
9. In the Project Location dialog box, browse to E:\Labfiles\Starter, and then click Select Folder.
10. In the New Project dialog box, click OK.

11. In the New app for SharePoint dialog box, in the What is the name of your app for SharePoint
box, type Corporate Structure App.
12. In the What SharePoint site do you want to use for debugging your app box, type
http://dev.contoso.com.
click Finish.
 Task 2: Import Starting Code

2. In File Explorer, browse to E:\Labfiles\Starting Code, and then double-click UIMarkup.txt.
3. In the How do you want to open this type of file (.txt)? dialog box, click Notepad.
4. In Notepad, on the Edit menu, click Select All.
5. On the Edit menu, click Copy.
7. In the Default.aspx file, delete everything between the <div> tag and the </div> tag.
8. Place the cursor between the two div tags, and then on the Edit menu, click Paste.
9. In Solution Explorer, expand Scripts.
10. Right-click App.js, and then click Delete.
12. In Solution Explorer, right-click Scripts, point to Add, and then click Existing Item.
13. In the Add Existing Item - CorporateStructureApp dialog box, browse to E:\Labfiles\Starting
Code.
14. Click App.js, and then click Add.
 Task 3: Link to the Taxonomy Script Library

1. In Visual Studio, in the Default.aspx code file, locate the following code:
<script type="text/javascript" src="/_layouts/15/sp.js"></script>
2. Immediately after the located code, on a new line, insert the following line of code:
<script type="text/javascript" src="/_layouts/15/sp.taxonomy.js"></script>
 Task 4: Configure App Permission Requests

2. In the AppManifest.xml designer, click the Permissions tab.
3. In the list of permissions, click the empty cell in the Scope column, and then click Taxonomy.
4. Click the empty cell in the Permission column, and then click Write.
5. In the list of permissions, click the empty cell in the Scope column, and then click Web.
6. Click the empty cell in the Permission column, and then click FullControl.
Results: A new SharePoint hosted app with a JavaScript framework, user interface, and JavaScript library
links is completed.
Exercise 2: Displaying the Existing Taxonomy Groups

 Task 1: Load the Term Store
1. In Solution Explorer, in the Scripts folder, double-click App.js.
2. In the App.js code window, locate the following line of code:
alert("loadTermStore is not yet implemented");
3. Replace the located code with the following line of code:
taxonomySession = SP.Taxonomy.TaxonomySession.getTaxonomySession(context);
4. Press Enter.
5. Type the following code:
termStore = taxonomySession.get_termStores().getByName("Managed Metadata Service

Application Proxy");
6. Press Enter.
L2-3
7. Type the following lines of code:
context.load(taxonomySession);
context.load(termStore);
8. Press Enter.
9. Type the following lines of code:
context.executeQueryAsync(
function () {
},
function (sender, args) {
});
10. Place the cursor in the first of the two anonymous functions.
$("#status-message").text("Term store loaded.");
12. Press Enter.

checkGroups();
14. Place the cursor in the second of the two anonymous functions.
$("#status-message").text("Error: Term store could not be loaded.");
 Task 2: Display the Groups

1. Place the cursor after the end of the loadTermStore function.
var checkGroups = function () {

};
3. Place the cursor within the checkGroups function you just created.
var groups = termStore.get_groups();
5. Press Enter.
context.load(groups);
7. Press Enter.
function () {
},
});
9. Place the cursor within the first of the two anonymous functions, and type the following code:
$("#groups-list").children().remove();
10. Press Enter.
var groupEnum = groups.getEnumerator();
12. Press Enter.
while (groupEnum.moveNext()) {
}
14. Place the cursor in the while loop you just created.
var currentGroup = groupEnum.get_current();
16. Press Enter.

var currentGroupID = currentGroup.get_id();
18. Press Enter.
var groupDiv = document.createElement("div");
20. Press Enter.
groupDiv.appendChild(document.createTextNode(currentGroup.get_name()));
22. Press Enter.
$("#groups-list").append(groupDiv);
24. Place the cursor within the second of the two anonymous functions.
$("#status-message").text("Error: Groups could not be loaded.");

L2-5
27. On the BUILD menu, click Rebuild Solution.
29. In the Windows Security dialog box, in the User name box, type Administrator.
31. On the Do you trust Corporate Structure App page, click Trust it.
32. When the page loads, under Existing Groups, verify that the app displays the text System.
Results: A SharePoint-hosted app that can display groups from the Managed Metadata service
application.
Exercise 3: Creating a Group, a Term Set, and Terms

 Task 1: Complete the Create Term Set Function
1. In the App.js code window, locate the following code:
alert("createTermSet is not yet implemented");
2. Replace the located code with the following code:
$("#status-message").text("Creating the group and term set...");
3. Press Enter.
corporateGroup = termStore.createGroup("Corporate Structure", corporateGroupGUID);
5. Press Enter.
context.load(corporateGroup);
7. Press Enter.
corporateTermSet = corporateGroup.createTermSet("Contoso", corporateTermSetGUID,

1033);
9. Press Enter.
context.load(corporateTermSet);
11. Press Enter.

});
13. Place the cursor in the first of the two anonymous functions.
$("#status-message").text("Group and term set created.");
15. Press Enter.
createTerms();
17. Place the cursor in the second of the two anonymous functions.
$("#status-message").text("Error: Group and term set creation failed.");
 Task 2: Create Terms in the New Term Set

1. Place the cursor after the end of the createTermSet function.
var createTerms = function () {

};
3. Place the cursor within the createTerms function.

$("#status-message").text("Creating terms…");
5. Press Enter.
var hrTerm = corporateTermSet.createTerm("Human Resources", 1033, hrTermGUID);
7. Press Enter.
context.load(hrTerm);
9. Press Enter.
var salesTerm = corporateTermSet.createTerm("Sales", 1033, salesTermGUID);
11. Press Enter.

L2-7
context.load(salesTerm);
13. Press Enter.
var technicalTerm = corporateTermSet.createTerm("Technical", 1033,

technicalTermGUID);
15. Press Enter.
context.load(technicalTerm);
17. Press Enter.
var engineeringTerm = technicalTerm.createTerm("Engineering", 1033,

engineeringTermGUID);
19. Press Enter.
context.load(engineeringTerm);
21. Press Enter.
var softwareTerm = technicalTerm.createTerm("Software", 1033, softwareTermGUID);
23. Press Enter.

context.load(softwareTerm);
25. Press Enter.
var supportTerm = technicalTerm.createTerm("Support", 1033, supportTermGUID);
27. Press Enter.
context.load(supportTerm);
29. Press Enter.

function () {
},
});
31. Place the cursor within the first of the two anonymous functions.
$("#status-message").text("Terms created.");
33. Press Enter.
checkGroups();
$("#status-message").text("Error: Could not create the terms.");

1. In Visual Studio, on the DEBUG menu, click Start Debugging.
4. In Internet Explorer, on the Do you trust Corporate Structure App? page, click Trust It.
7. In Internet Explorer, on the Page Title page, examine the taxonomy groups that already exist.
8. Click Create Corporate Term Set.

9. The app creates and displays the new term set.
Administration.
14. In the list of service applications, click Managed Metadata Service Application.
15. In the Taxonomy Term Store list, expand the Corporate Structure group.
16. Expand the Contoso term set.
17. Expand the Technical term.

L2-9
Results: A SharePoint hosted app that can create a new group and a new empty term set in a term store.
Lab B: Developing Managed Metadata

Solutions (Part 2)
Exercise 1: Obtaining the Host Web
 Task 1: Obtain a Web Info Object for the Host Web
2. In File Explorer, browse to E:\Labfiles\Starter\CorporateStructureApp, and then double-click

CorporateStructureApp.sln.
3. In the How do you want to open this type of file (.sln)? dialog box, click Visual Studio 2012.
4. In Solution Explorer, in the Scripts folder, double-click App.js.
5. In the App.js code window, locate the following line of code:
alert("createColumns is not yet implemented");
$("#status-message").text("Obtaining the host web...");
7. Press Enter.
var hostwebinfo = context.get_web().get_parentWeb();
9. Press Enter.
context.load(hostwebinfo);
11. Press Enter.

function () {
},
});
 Task 2: Obtain the Host Web

hostweb = context.get_site().openWebById(hostwebinfo.get_id());
3. Press Enter.
context.load(hostweb);
L2-11
5. Press Enter.
function () {
},
});
$("#status-message").text("Parent web loaded.");
9. Press Enter.
addColumns();
$("#status-message").text("Could not load parent web");
Results: A SharePoint app that has a reference to the host web in preparation for creating site columns in
the host web.
Exercise 2: Adding Metadata Site Columns

 Task 1: Add Metadata Site Columns to the Host Web
1. Place the cursor after the end of the createColumns function.
var addColumns = function () {

};
3. Place the cursor within the addColumns function.
$("#status-message").text("Creating site columns...");
5. Press Enter.
var webFieldCollection = hostweb.get_fields();
7. Press Enter.
var noteField = webFieldCollection.addFieldAsXml(xmlNoteField, true,

9. Press Enter.
context.load(noteField);
11. Press Enter.
metaDataField = webFieldCollection.addFieldAsXml(xmlMetaDataField, true,

13. Press Enter.

context.load(metaDataField);
15. Press Enter.
function () {
},
});
$("#status-message").text("Columns added.");
19. Press Enter.
connectFieldToTermSet();
$("#status-message").text("Error: Could not create the columns.");
 Task 2: Connect a Metadata Site Column to a Term Set

1. Place the cursor after the end of the addColumns function.
var connectFieldToTermSet = function () {

};
L2-13
3. Place the cursor within the connectFieldToTermSet function.
$("#status-message").text("Connecting the columns to the term set");
5. Press Enter.
var sspID = termStore.get_id();
7. Press Enter.
var metaDataTaxonomyField = context.castTo(metaDataField, SP.Taxonomy.TaxonomyField);
9. Press Enter.
context.load(metaDataTaxonomyField);
11. Press Enter.
function () {
},
});
metaDataTaxonomyField.set_sspId(sspID);
15. Press Enter.

metaDataTaxonomyField.set_termSetId(corporateTermSetGUID);
17. Press Enter.
metaDataTaxonomyField.update();
19. Press Enter.
function () {
},
});
$("#status-message").text("Connection made. Operations complete.");
$("#status-message").text("Error: Could not connect the taxonomy field.");

2. In the address bar, type http://dev.contoso.com, and then press Enter.

5. On the Contoso Development Site page, click the Settings icon in the top-right corner of the page,
and then click Site settings.
6. Under Web Designer Galleries, click Site columns.
7. Locate the Custom Columns category and note the columns listed.

12. On the Do you trust Corporate Structure App? page, click Trust It.
15. On the Page Title page, click Create Corporate Site Columns.
16. When the operations are complete, switch to the other instance of Internet Explorer.
17. In the address bar, click the Refresh icon.
18. Locate the Custom Columns category and note the presence of the Corporate Unit site column.
19. Click Corporate Unit.
20. Locate the Term Set Settings section, expand Managed Metadata Service Application Proxy, and
then expand Corporate Structure.
21. Note that the column is bound to the Contoso term set.
22. Close both instances of Internet Explorer.
Results: A SharePoint-hosted app that can create site columns for metadata.
L3-1
Module 3: Interacting with the Search Service

Lab: Executing Search Queries from
SharePoint Apps
Exercise 1: Submitting Search Queries from Client-Side Code
 Task 1: Create a New SharePoint App
password Pa$$w0rd.
4. In Visual Studio 2012, on the Start Page, click New Project.

5. In the New Project dialog box, in the Templates list, expand Visual C#, expand Office/SharePoint,
and then click Apps
6. In the central pane, click App for SharePoint 2013

7. In the Name box, type SearchApp.
9. In the New app for SharePoint dialog box, in the What SharePoint site do you want to use for
debugging your app? box, type http://dev.contoso.com.
10. In the How do you want to host your app for SharePoint? list, click SharePoint-hosted and then
click Finish.
11. In the Default.aspx file, locate and delete the following code:
<div>
<p id="message">

initializing...
</p>
</div>
12. Add the following code:
<input id="txtSearch" type="text" />

<button id="btnSearch" type="button" onclick="DoSearch();">Go</button>
<br />
<br />
<div id="search-title"></div>
<br />
<br />
<div id="search-results"></div>
13. In Solution Explorer, expand the Scripts folder and then double-click the App.js file.
14. On the Start screen, click Computer.
15. In File Explorer, browse to E:\Labfiles\Starter, and then double-click App.js.

16. In the How do you want to open the type of file (.js)? dialog box, click More options, and then
click Notepad.
17. In Notepad, on the Edit menu, click Select All.
18. On the Edit menu, click Copy.
19. Switch to Visual Studio 2012.
20. In Visual Studio, on the EDIT menu, click Select All.
21. On the EDIT menu, click Paste.
23. On the Permissions tab, click the Scope column of the first row, and then click Search.
24. Click the Permission column, and then click QueryAsUserIgnoreAppPrincipal.

25. Click the Scope column of the second row, and then click Web.
26. Click the Permission column of the second row, and then click Read.
28. On the Do you trust SearchApp page, click Trust It.
29. On the SearchApp page, in the search text box, type Contoso, and then click Go. You should see
results presented in the app web page. This may take one to two minutes.
Results: A new SharePoint App that uses Search REST API calls.
Exercise 2: Using a Custom Action to Launch A Search App

 Task 1: Add a Custom Action to Call App Page
1. In Solution Explorer, right-click SearchApp, point to Add, and then click New Item.
2. In the Add New Item - SearchApp dialog box, in the center pane, click Menu Item Custom Action.
3. In the Name box, type SearchAction, and then click Add.
4. In the Create Custom Action for Menu Item dialog box, under Where do you want to expose the
custom action?, confirm that Host Web is selected.
5. In the Where is the custom action scoped to? list, ensure List Template is selected.
6. In the Which particular item is the custom action scoped to? list, click Document Library, and
then click Next.
7. In the What is the text on the menu item? box, type Search.
8. In the Where does the custom action navigate to? list, confirm that
SearchApp\Pages\Default.aspx is selected, and then click Finish.
9. In the open Elements.xml file, in the UrlAction element, change the value of the Url attribute to the
following:
~appWebUrl/Pages/Default.aspx?{StandardTokens}
&HostUrl={HostUrl}&Source={Source}
&ListURLDir={ListUrlDir}
&ListID={ListId}&ItemURL={ItemUrl}&ItemID={ItemId}

L3-3
11. In the App.js file, locate the following code:
var scriptbase = hostweburl + "/_layouts/15/";

$.getScript(scriptbase + "SP.RequestExecutor.js");
var clientContext = new SP.ClientContext.get_current();

var parentCtx = new SP.AppContextSite(clientContext, hostweburl)
var web = parentCtx.get_web();
clientContext.load(web);
var listId = GetListId();
list = web.get_lists().getById(listId);
clientContext.load(list);
var itemId = GetItemId();
currentItem = list.getItemById(itemId);
clientContext.load(currentItem);
clientContext.executeQueryAsync(onListLoadSucceeded,
onRequestFailed);
13. Locate the following code:
clientContext.executeQueryAsync(onListLoadSucceeded,
onRequestFailed);
});
function onListLoadSucceeded() {
title = currentItem.get_fieldValues().Title;
getSearchResults(title);
}
function onRequestFailed(sender, args) {
alert('Error:' + args.get_message());
}
16. In Solution Explorer, right-click SearchApp, and then click Deploy.

17. On the Do you trust SearchApp? page, click Trust It.
18. You will test the menu item custom action in the next task.
 Task 2: Test the Custom Action and Search App

1. In the browser window, in the Address bar, type http://dev.contoso.com, and then press Enter.
2. On the Contoso Development Site page, in the Quick Launch menu, click Documents.
3. On the Documents page, on the Northwind Traders Contract row, click the ellipsis.
4. In the Northwind Traders Contract.docx dialog box, click the ellipses, and then click Search. You
will be redirected to the App web page and a search is performed based on the Title of the
document.
Note: At this point, the app is only designed to run only when a user clicks the custom action menu
item labeled Search. If you try to debug the app directly, you will see a JavaScript error because there is
no list item associated with the app. You must deploy the app and launch it from the Edit Control Block
on a document.
Results: A new custom action that directs to a SharePoint App.

L4-1
Module 4: Customizing the Search Experience

Lab A: Configuring Result Types and Display
Templates
Exercise 1: Configuring and Testing a Result Type
 Task 1: Create and Test a Custom Result Type
3. On the Windows Start page, type SharePoint, and then click SharePoint Designer 2013.
5. In the Open Site dialog box, in the Site name box, type http://search.contoso.com, and then click
Open.
8. In the Navigation pane, click All Files.
9. Click _catalogs, click masterpage, click Display Templates, and then click Search.
10. Right-click Item_Default.html, and then click Copy.

11. On the ALL FILES tab, click Paste.
12. Press F2, type Item_Tasks.html, and then press Enter.
13. Click the Item_Tasks.html text to display template file.
14. On the ribbon, click Edit File.
15. Change the <title> element to Task Item.
16. Press Ctrl+S to save the file.

20. Under Web Designer Galleries, click Master pages and page layouts.
21. Click Display Templates.
22. Click Search.

23. Using the arrow navigation at the bottom of the page, browse to the Item_Tasks.html display
template. Notice that the Item_Tasks.js file was automatically created for you.
24. Select the Item_Tasks.html check box.
25. On the ribbon, on the FILES tab, click Edit Properties. Note the Title is what you typed in the file
from above.
26. Under Target Control Type (Search), select all the check boxes, and then click Save.
27. Click Settings, and then click Site Settings.
28. Under Site Collection Administration, click Search Result Types.
29. On the Manage Result Types page, click New Result Type.
30. On the Add Result Type page, in the Give it a name box, type Tasks.
31. Click Show more conditions to expand the advanced conditions area.
32. In the Which custom properties should match? list, click ContentType.
33. In the Enter value for property box, type Task.
34. In the What should these result look like? list, click Task Item, and then click Save.
35. At the top of the page, click Contoso Search.

36. On the Search page, in the text box, type ContentType:Task, and then press Enter.
37. SharePoint will display five results. Notice that there is no visual difference between the new display
template and the standard (out-of-the-box) display template.
Note: You will customize the Item Task display template in the next exercise.
Results: After completing this lab, you should have created a new result type and a new display template.
Exercise 2: Customizing an Item Display Template

 Task 1: Customize an Item Display Template
3. Replace it with the following code:
<h3>
<img src="/_layouts/images/icon_tasklist.gif" style="padding-right:5px;border:0px"/>
Title: <a href='_#=ctx.CurrentItem.Path=#_'>_#=ctx.CurrentItem.Title=#_</a><br />
Assigned To: _#=ctx.CurrentItem.AssignedTo=#_<br />
</h3>
Note: You may notice that SharePoint Designer displays some schema errors in the HTML
file. You can safely ignore these errors.
4. On the Quick Access Toolbar, click Save.
5. In the Confirm Save dialog box, click Yes.
7. In Internet Explorer, click the Contoso Search site logo.
8. On the Search page, in the text box, type Project, and then press Enter. Notice that the results use
your new display template.
L4-3
Results: After completing this exercise, you should have customized an item display template.
Exercise 3: Customizing a Hover Panel Display Template

 Task 1: Create and Customize a Hover Panel Display Template
3. If the Building the report message appears, click Refresh.
5. Right-click Item_Default_HoverPanel.html, and then click Copy.
6. On the ribbon, click Paste.
7. Press F2, type Item_Tasks_HoverPanel.html, and then press Enter.
8. Double-click the Item_Tasks.html display template file.

Templates/Search/Item_Default_HoverPanel.js";
11. Replace it with the following code::

Templates/Search/Item_Tasks_HoverPanel.js";
14. If the Building the report message appears, click Refresh.
16. Double-click the Item_Tasks_HoverPanel.html display template file.
18. In the Item_Tasks_HoverPanel.html file, locate the following code:
_#= ctx.RenderBody(ctx) =#_
<br/>
Modified: _#=ctx.CurrentItem.LastModifiedTime =#_
22. In Internet Explorer, click the Contoso Search site logo.

23. On the Search page, in the text box, type Project, and then press Enter.
24. Move the mouse over one of the results. Notice that the hover panel appears, showing the Modify
date.
25. Close Internet Explorer, and then close SharePoint Designer 2013.
Results: After completing this exercise, you should have created a hover panel display template for your
custom Task result type.
L4-5
Lab B: Configuring Entity Extraction

Exercise 1: Creating and Deploying an Entity Extractor
 Task 1: Create and Deploy an Entity Extractor Input File
password Pa$$w0rd.
4. In File Explorer, browse to the E:\Labfiles\Starter folder.
5. On the Quick Access Toolbar, click New folder, type EntityExtractor, and then press Enter.
6. Right-click the EntityExtractor folder, point to Share with, and then click Specific people.
7. In the File Sharing dialog box, in the text box, type SPFarm, click Add, and then click Share.
8. In the File Sharing dialog box, click Done.

9. In File Explorer, browse to the E:\Labfiles\Starter\EntityExtractor folder.
10. Right-click in the empty folder, point to New, and then click Text Document.
11. Type Memory, and then press Enter.
12. Right-click Memory.txt, and then click Edit.
13. Add the following to the file:
Key, Display form

512MB, 512MB
1024MB, 1GB
1GB, 1GB
2GB, 2GB
4GB, 4GB
8GB, 8GB
16GB, 16GB
14. On the File menu, click Save.
15. On the Windows Start page, type SharePoint, and then click SharePoint 2013 Management Shell.
16. At the command prompt, type the following code, and then press Enter:
17. At the command prompt, type the following code, and then press Enter:
Import-SPEnterpriseSearchCustomExtractionDictionary -SearchApplication $searchApp -

FileName \\London\EntityExtractor\Memory.txt -DictionaryName
Microsoft.UserDictionaries.EntityExtraction.Custom.Word.1
 Task 2: Configure a Managed Property for Entity Extraction

Administration.

3. Click the Contoso Search Search Service Application.
4. In quick launch, under Queries and Results, click Search Schema.
5. In the Managed property box, type Title, and then press Enter.
6. Under Property Name, click Title.
7. In the Custom entity extraction section, select the Word Extraction - Custom1 check box, and
then click OK.
8. In the Managed property box, type Description, and then press Enter.
9. Under Property Name, click Description.
10. In the Custom entity extraction section, select the Word Extraction - Custom1 check box, and
then click OK.
11. In quick launch, under Crawling, click Content Sources.
12. Right-click Local SharePoint sites, click Start Full Crawl.
13. In the Message from Webpage dialog box, click OK.
14. Wait for the crawl to complete. Click Refresh until the Status reads Idle.
 Task 3: Configure Refinement Based on Extracted Entities

1. In Internet Explorer, click New Tab.
3. On the Search page, in the text box, type mp3 player, and then press Enter, several results appear.
4. Click the Settings icon, and then click Edit page.
5. In the Navigation Zone section, in the Refinement section, click the Refinement Web Part Menu
drop-down arrow, and then click Edit Web Part.
6. In the Refinement section, click the Choose Refiners button.
7. In the Refinement configuration for ‘Refinement’ dialog box, in the Available refiners box, click
WordCustomRefiner1, and then click Add>.
8. In the Display name box, type Memory, and then click OK.
9. In the Refinement section, click OK
10. On the ribbon, click Save.
11. Click the Contoso Search site logo.
12. On the Search page, in the text box, type mp3 player, and then press Enter. Several results appear.
Notice the new memory refiner on the left.
13. Click 8GB. Results appear that have 8GB in the title or description.
Results: After completing this exercise, you should have created, deployed, and tested a custom entity
extractor.
L5-1
Module 5: Implementing Enterprise Content Management

Lab: Implementing Content Management
Functionality
Exercise 1: Creating a Custom Document ID Provider
 Task 1: Create a New Project and Add a Class
1. On the Windows Start screen, click Visual Studio 2012.
3. In the New Project dialog box, in the hierarchy of templates, expand Visual C#, expand
Office/SharePoint, and then click SharePoint Solutions.
4. In the list of templates, click SharePoint 2013 - Empty Project.

5. In the Name box, type ContosoDocumentIDProvider.
6. Next to the Location box, click Browse.
7. In the Project Location dialog box, browse to E:\Labfiles\Starter, and then click Select Folder.
8. In the New Project dialog box, click OK.
9. In the SharePoint Customization Wizard dialog box, in the What site do you want to use for
debugging box, type http://dev.contoso.com, and then click Validate.
11. Click Deploy as a farm solution, and then click Finish.
12. In Solution Explorer, right-click ContosoDocumentIDProvider, point to Add, and then click Class.
13. In the Add New Item - ContosoDocumentIDProvider dialog box, in the Name box, type
DocumentIDProvider, and then click Add.
14. In Solution Explorer, right-click References, and then click Add Reference.
15. In the Reference Manager - ContosoDocumentIDProvider dialog box, under Assemblies, click
Extensions.
16. In the list of extensions, click Microsoft.Office.DocumentManagement, and then select the check
box that appears.
17. In the list of extensions, click Microsoft.Office.Policy, select the check box that appears, and then
click OK.
18. In the DocumentIDProvider.cs code window, locate the following line of code:
using System.Threading.Tasks;
19. Immediately after this located code, type the following code:
using System.Data;
using Microsoft.Office.DocumentManagement;
namespace ContosoDocumentIDProvider
namespace Contoso.ContentManagement
class DocumentIDProvider
class DocumentIDProvider : DocumentIdProvider
 Task 2: Code Document ID Creation

1. In the DocumentIDProvider.cs code file, place the cursor within the DocumentIDProvider class.
private string docIdFormatString = "Contoso{0}";
3. Press Enter.
4. Type override followed by a space, and then double-click GenerateDocumentId.

throw new NotImplementedException();
if (listItem == null)
{
throw new ArgumentNullException("listItem");
}
7. Press Enter.
Random random = new Random();
9. Press Enter.
int randomNumber = random.Next(100000, 999999);
11. Press Enter.
return string.Format(this.docIdFormatString, randomNumber);
 Task 3: Code Custom Searches

1. In the DocumentIDProvider.cs code file, place the cursor within the DocumentIDProvider class, but
outside any method.
2. Type override followed by a space, and then double-click GetDocumentUrlsById.

L5-3
List<string> itemUrls = new List<string>();
5. Press Enter.
if (site != null && !string.IsNullOrEmpty(documentId)) {

}
7. In Solution Explorer, right-click ContosoDocumentIDProvider, point to Add, and then click Existing
Item.
8. In the Add Existing Item - ContosoDocumentIDProvider dialog box, browse to E:\Labfiles\C#

Code, click DocumentFinder.cs, and then click Add.
9. Place the cursor within the if statement you just created.
itemUrls = DocumentFinder.FindByDocumentId(site, documentId);
11. Place the cursor at the end of the GetDocumentUrlsById method.
if (itemUrls.Count == 0)
{
return null;
}
else
{
return itemUrls.ToArray();
}
 Task 4: Complete the Document ID Provider

1. In the DocumentIDProvider.cs code file, place the cursor within the DocumentIDProvider class, but
outside any method.
2. Type override followed by a space, and then double-click GetSampleDocumentIdText.
return string.Format(this.docIdFormatString, "123456");
5. Place the cursor within the DocumentIDProvider class, but outside any method.
6. Type override followed by a space, and then double-click DoCustomSearchBeforeDefaultSearch.

get { throw new NotImplementedException(); }
get { return true; }
Results: A Microsoft Visual Studio® project with a custom document ID provider class coded and
completed.
Exercise 2: Registering a Custom Document ID Provider

 Task 1: Add a Feature Receiver
1. In Solution Explorer, right-click Features, and then click Add Feature.
2. In Solution Explorer, right-click Feature1, and then click Rename.
3. Type ContosoDocIDFeature, and then press Enter.
4. In the ContosoDocIDFeature.feature designer, in the Title box, type Contoso Document ID

Provider.
5. In the Description box, type This feature enables the Contoso Document ID Provider.
6. In the Scope list, click Site.
7. In Solution Explorer, right-click ContosoDocIDFeature, and then click Add Event Receiver.
8. In the ContosoDocIDFeature.EventReceiver.cs code window, delete all the comments within the
ContosoDocIDFeatureEventReceiver class.
 Task 2: Set the Document ID Provider on Activation

1. In the ContosoDocIDFeature.EventReceiver.cs code file, locate the following line of code:
2. Immediately after the located code, insert the following line of code:
using Microsoft.Office.DocumentManagement;
3. Place the cursor within the ContosoDocIDFeatureEventReceiver class.
4. Type override followed by a space, and then double-click FeatureActivated.

base.FeatureActivated(properties);

L5-5
7. Press Enter.
DocumentId.SetProvider(site, new Contoso.ContentManagement.DocumentIDProvider());
 Task 3: Set the Default Document ID Provider on Deactivation

1. In the ContosoDocIDFeature.EventReceiver.cs code file, place the cursor in the
ContosoDocIDFeatureEventReceiver class, but outside any method.
2. Type override followed by a space, and then double-click FeatureDeactivating.
base.FeatureDeactivating(properties);
5. Press Enter.
DocumentId.SetDefaultProvider(site);
 Task 4: Test the Document ID Provider

1. On the Windows Start screen, click Internet Explorer.
5. Click the Settings icon, and then click Site settings.
6. Under Site Collection Administration, click Site collection features.
7. Next to the Document ID Service feature, click Activate.
9. Under Site Collection Administration, click Document ID settings.
Note: Notice that you can add your own prefix for document IDs.
10. In Visual Studio, on the DEBUG menu, click Start Without Debugging. Wait for the deployment to
complete before you continue.
11. In the first instance of Internet Explorer (which is displaying the Document ID Settings), refresh the
page.
Note: The page shows a message informing you that a custom document ID provider has
been configured. Notice that you cannot edit the prefix for document IDs.
12. In the Quick Launch on the left, click Documents.
13. Click new document.
14. In the Add a document dialog box, click Browse.
15. In the Choose File to Upload dialog box, browse to E:\Labfiles\Test Documents, click Test
Document.docx, and then click Open.
16. In the Add a document dialog box, click OK.
17. In the ribbon, click the LIBRARY tab.
18. In the Manage Views section, click Modify View.
19. In the list of Columns, select the check box to the left of Document ID (linked to document), and
then click OK.
Results: A completed document ID provider in a SharePoint solution.
Exercise 3: Applying a Custom Audit Policy

 Task 1: Export an Information Management Policy
1. On the Windows Start screen, click Internet Explorer.


6. Under Site Collection Administration, click Content Type Policy Templates.
7. Click Create.
8. On the Edit Policy page, in the Name box, type Contoso Audit Policy.
9. In the Administrative Description box, type This policy ensures auditing for reading and editing
items.
10. In the Policy Statement box, type A policy is applied to this document that audits access.
11. Select the Enable Auditing check box.
12. Select the Opening or downloading documents, viewing items in lists, or viewing item
properties check box.
13. Select the Editing items check box, and then click OK.
14. In the list of policies, click Contoso Audit Policy.
15. On the Edit Policy page, click Export.
16. In the Do you want to open or save Contoso Audit Policy.xml from dev.contoso.com? message
box, in the Save list, click Save as.
17. In the Save As dialog box, browse to the root of the C: drive.
18. Click New folder, type Policies, and then press Enter.
L5-7
19. Double-click the Policies folder, and then click Save.
20. In the The Contoso Audit Policy.xml download has completed message box, click Open folder.
24. In the list of policies, click Contoso Audit Policy.
25. On the Edit Policy page, click Delete.
 Task 2: Create a Feature Receiver

2. In Solution Explorer, right-click Features, and then click Add Feature.
3. In Solution Explorer, right-click Feature1, and then click Rename.
4. Type ContosoAuditingFeature, and then press Enter.

5. In the ContosoAuditingFeature.feature editor, in the Title box, type Contoso Auditing Feature.
6. In the Description box, type Sets up auditing for documents in Contoso sites.
8. In Solution Explorer, right-click ContosoAuditingFeature, and then click Add Event Receiver.
9. In the ContosoAuditingFeature.EventReceiver.cs code window, delete all the comments within the
ContosoDocIDFeatureEventReceiver class.
 Task 3: Code the Policy Import

1. In the ContosoAuditingFeature.EventReceiver.cs code file, locate the following line of code:
2. Immediately after the located code, insert the following code:
using System.Xml;
using Microsoft.Office.RecordsManagement.InformationPolicy;
using System.IO;
3. Place the cursor within the ContosoAuditingFeatureEventReceiver class.
4. Type override followed by a space, and then double-click FeatureActivated.
base.FeatureActivated(properties);
7. Press Enter.

9. Press Enter.
XmlDocument policyXmlDoc = new XmlDocument();
11. Press Enter.
policyXmlDoc.Load("C:\\Policies\\Contoso Audit Policy.xml");
13. Press Enter.
StringWriter stringWriter = new StringWriter();
15. Press Enter.
XmlTextWriter xmlTextWriter = new XmlTextWriter(stringWriter);
17. Press Enter.
policyXmlDoc.WriteTo(xmlTextWriter);
19. Press Enter.

string policyXml = stringWriter.ToString();
21. Press Enter.
PolicyCollection.Add(site, policyXml);
23. Press Enter.
24. Switch to File Explorer and verify that the contents of the C:\Policies folder is displayed.
25. Double-click Contoso Audit Policy.xml.
26. In the How do you want to open this type of file (.xml)? dialog box, click Microsoft Visual Studio
2012.
27. In the Contoso Audit Policy.xml code window, in the <p: Policy> element, select the value of the
id element.
28. On the EDIT menu, click Copy.
29. Switch to the ContosoAuditingFeature.EventReceiver.cs code window.
Policy newPolicy = policyCatalog.PolicyList["

L5-9
32. Type the following code on the same line:
"];
33. Press Enter.
SPContentType docContentType = site.RootWeb.ContentTypes["Document"];
35. Press Enter.
Policy.CreatePolicy(docContentType, newPolicy);
 Task 4: Code Policy Removal

1. Place the cursor within the ContosoAuditingFeatureEventReceiver class, but outside any method.
2. Type override followed by a space, and then double-click FeatureDeactivating.

base.FeatureDeactivating(properties);
5. Press Enter.
SPContentType docContentType = site.RootWeb.ContentTypes["Document"];
7. Press Enter.
Policy.DeletePolicy(docContentType);
9. Press Enter.
10. Switch to the Contoso Audit Policy.xml code window.
11. In the Contoso Audit Policy.xml code window, in the <p: Policy> element, select the value of the
id element.
12. On the EDIT menu, click Copy.
13. Switch to the ContosoAuditingFeature.EventRecevier.cs code file.

PolicyCollection.Delete(site, "

16. Type the following code on the same line:
");
 Task 5: Test the Information Management Policy


Note: Notice that the Contoso Audit Policy you deleted has been recreated by the
feature receiver.
6. In the Quick Start on the left, click Documents.
7. In the ribbon, click the LIBRARY tab.
8. In the Settings section, click Library Settings.
9. Under Permissions and Management, click Information management policy settings.
10. Under Content Type Policies, click Document.
Note: Notice that the information management policy for the Document content type is
taken from Contoso Audit Policy.
Results: A SharePoint solution that imports and applies an information management policy when it is
activated.
L6-1
Module 6: Developing a Publishing Site for Web Content

Lab: Customizing a SharePoint Publishing
Site
Exercise 1: Building a Custom Page Field Control
 Task 1: Create Rendering Templates
password Pa$$w0rd.
4. On the Visual Studio Start Page, click Open Project.

5. In the Open Project dialog box, browse to E:\Labfiles\Starter\Layouts, click
Contoso.Website.Layouts.sln, and then click Open.
6. In Solution Explorer, right-click Contoso.Website.Layouts, point to Add, and then click SharePoint
Mapped Folder.
7. In the Add SharePoint Mapped Folder dialog box, expand TEMPLATE, click
CONTROLTEMPLATES, and then click OK.
8. In Solution Explorer, right-click the CONTROLTEMPLATES folder, point to Add, and then click New
Item.
9. In the Add New Item - Contoso.Website.Layouts dialog box, in the Office/SharePoint group, click
User Control (Farm Solution only).
10. In the Name box, type Contoso.ProductCodeTemplate.ascx, and then click Add.
11. Double-click the Contoso.ProductCodeTemplate.ascx file.

<SharePoint:RenderingTemplate ID="ContosoProductCodeRenderingTemplate"
runat="server">
<Template>
<asp:RegularExpressionValidator ID="ProductCodeValidator" runat="server"
ControlToValidate="ProductCodeTextBox"
ErrorMessage="Please enter a valid product code in the format @@@-####."
ValidationExpression="^[A-Z]{3}[0-9]{4}$" />
</Template>
<SharePoint:RenderingTemplate ID="ContosoProductCodeDisplayRenderingTemplate"
runat="server">
<Template>
<asp:HyperLink ID="ProductCodeHyperLink" runat="server" />
</Template>
Note: If you prefer, you can copy this markup from the text file at
E:\Starter\Snippets\RenderingTemplate.txt.
L6-2 Developing Microsoft SharePoint 2013 Advanced Solutions
 Task 2: Create a Field Control

1. In Solution Explorer, right-click the FieldControls folder, point to Add, and then click Class.
2. In the Add New Item - Contoso.Website.Layouts dialog box, click Class.
3. In the Name box, type ProductCodeField, and then click Add.
4. In the ProductCodeField.cs file, append the following using statements:
using System.Web.UI.WebControls;
using Microsoft.SharePoint.WebControls;
class ProductCodeField
{
}
public class ProductCodeField : BaseFieldControl

{
}
7. Place the cursor in the class body, and then add the following code:

protected RegularExpressionValidator ProductCodeValidator;
protected HyperLink ProductCodeHyperLink;
{
}
public override string DisplayTemplateName
{
get { return "ContosoProductCodeDisplayRenderingTemplate"; }
}
{
if ( this.ControlMode == SPControlMode.Display )
{
ProductCodeHyperLink =
(HyperLink)this.TemplateContainer.FindControl("ProductCodeHyperLink");
ProductCodeHyperLink.NavigateUrl =
String.Format("{0}/Products?ProductCode={1}", SPContext.Current.Web.Url,
(string)this.ItemFieldValue);
ProductCodeHyperLink.Text = (string)this.ItemFieldValue;
}
else
{
ProductCodeTextBox =
(TextBox)this.TemplateContainer.FindControl("ProductCodeTextBox");
ProductCodeValidator =
(RegularExpressionValidator)this.TemplateContainer.FindControl("ProductCodeValidator"
);
}
}
{
get
{
L6-3
}
set
{
ProductCodeTextBox.Text = (string)this.ItemFieldValue;
}
}
Note: If you prefer, you can copy this code from the text file at
E:\Starter\Snippets\ProductFieldCode.txt.
Results: After completing this exercise, you should have created a User Control containing rendering
templates, and a custom field control.
Exercise 2: Building a Page Layout

 Task 1: Add Content Controls to a Page Layout
1. In Solution Explorer, expand the PageLayouts folder, expand the ProductArticleLayout folder, and
then double-click ProductArticleLayout.aspx.
<%@ Register Tagprefix="ContosoWebControls"

Namespace="Contoso.Website.Layouts.FieldControls" Assembly="Contoso.Website.Layouts,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=8dec8fdacbd4988c" %>
3. In the code editor, add a content placeholder by appending the following code:
<asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">

<PublishingWebControls:EditModePanel ID="EditModePanel" runat="server"
CssClass="edit-mode-panel title-edit">
<SharePointWebControls:TextField ID="TitleField" runat="server"
FieldName="Title"/>
</PublishingWebControls:EditModePanel>
<ContosoWebControls:ProductCodeField ID="ProductCodeField"
FieldName="ContosoProductCode" runat="server"></ContosoWebControls:ProductCodeField>
<PublishingWebControls:RichHtmlField ID="PageContentField"
FieldName="PublishingPageContent" HasInitialFocus="True" MinimumEditHeight="400px"
runat="server"/>
<WebPartPages:WebPartZone ID="Full " Title="Full" runat="server">
<ZoneTemplate></ZoneTemplate>
</asp:Content>
5. Right-click Contoso.Website.Layouts, and then click Deploy.
 Task 2: Deploy and Test the Page Layout

2. In Internet Explorer, in the address bar, type http://www.contoso.com, and then press Enter.
3. On the Contoso Pharmaceuticals page, click the Sign In link.

4. Click the Settings icon, and then click Site contents.
5. On the Site Contents page, click the Pages app.
6. On the FILES tab, click New Document.
7. On the Create Page page, in the Title box, type My Product Article.
8. In the Page Layout list, click (Product Article Page) Product Article, and then click Create.
9. On the Pages page, click My-Product-Article.
10. On the PAGE tab, click Edit.
11. In the Product Code box, type ABC123J, and then press Tab.
Note: A message should appear next to the Product Code edit box requesting that you enter a valid
product code. This validates that our RegEx validation for product code is working properly.
12. In the Product Code box, type ABC1234, and then press Tab.
13. At the bottom of the page, click Add a Web Part.
Note: The Add the Part gallery should open, allowing you to browse web parts to add to the page.
This validates that our Web Part Zone control is configured correctly.
14. Click Cancel.
15. On the Publish tab, click Publish.
16. In the Publish dialog box, click Continue.
17. Position the cursor on the ABC1234 text. At the bottom of the screen, notice that the URL of the
hyperlink is set to http://www.contoso.com/products?ProductCode=ABC1234.
Note: The previous step verifies our custom field control is properly rendering the display template
that formats the product code as a hyperlink.
Results: After completing this lab, you will have learned how to build and deploy page layouts that
include page field controls and web parts.
L7-1
Module 7: Structuring and Publishing Websites for All Users

Lab A: Structuring a SharePoint Publishing
Site
Exercise 1: Creating a Navigation Term Set
 Task 1: Create a New Navigation Term Set
5. On the Home page, review the navigation at the top of the page.
7. Under Look and Feel, click Navigation, and notice how the navigation is set to structural for both
the global and the current navigation areas.
Administration.
11. Click Managed Metadata Service.
12. On the Term Store Management Tool page, in the TAXONOMY TERM STORE section, notice that
there is no term group called Navigation.

15. In the Open Project dialog box, browse to E:\Labfiles\Starter, click CreateNavigation.sln, and then
click Open.
16. Right-click CreateNavigation, and then click Add Reference.
17. In the Reference Manager - CreateNavigation dialog box, click Browse.
18. In the Select the files to reference dialog box, browse to C:\Program Files\Common
Files\microsoft shared\Web Server Extensions\15\ISAPI, select the
Microsoft.SharePoint.Taxonomy.dll, Microsoft.SharePoint.dll, and
Microsoft.SharePoint.Publishing.dll assemblies, and then click Add.
19. In the Reference Manager - CreateNavigation dialog box, click OK.
20. In Solution Explorer, double-click Program.cs.

21. In the Program.cs file, add the following using statements:
using Microsoft.SharePoint.Administration;
using Microsoft.SharePoint.Navigation;
using Microsoft.SharePoint.Taxonomy;

{
}
23. Below the located code, add the following code to define the CreateGroup method:
static Group CreateGroup(TermStore termStore, string name)

{
Group g = null;
try
{
g = termStore.Groups[name];
}
catch (Exception ex) {}
if (g == null)
{
g = termStore.CreateGroup(name);
}
return g;
}
Note: If you prefer, you can copy the CreateGroup method from the text file at
E:\Labfiles\Starter\Snippets\CreateGroup.txt.
24. Add the following code to define the CreateNavigationTermSet method:
static void CreateNavigationTermSet(Group group, string name)

{
TermSet termSet = null;
try
{
termSet = group.TermSets[name];
}
catch (Exception ex) { }
if (termSet == null)
{
//create term set
termSet = group.CreateTermSet(name);
termSet.Description = name;
termSet.IsAvailableForTagging = true;
termSet.IsOpenForTermCreation = true;
//set properties
termSet.TermStore.CommitAll();
}
}
L7-3
at E:\Labfiles\Starter\Snippets\CreateNavigationTermSet.txt.

{
26. Below the located code, add the following code:

{
TaxonomySession session = new TaxonomySession(site);
TermStore termStore = session.TermStores["Managed Metadata Service"];
Group group = CreateGroup(termStore, "Navigation");
CreateNavigationTermSet(group, "Intranet");
}
29. On the Term Store Management Tool page, click Refresh, notice the new Navigation term group
appears.
30. Expand Navigation, and notice the Intranet term set.
 Task 2: Add Navigation Terms

1. Switch to Visual Studio
2. In the Program.cs file, locate the following code:
}
}
static void CreateNavigationTerms(TermSet termSet)

{
//create terms
Term t = termSet.CreateTerm("Home", 1033);
t.SetLocalCustomProperty("_Sys_Nav_TargetUrl", "/Pages/Home.aspx");
t = termSet.CreateTerm("Intranet", 1033);
"http://intranet.contoso.com/Pages/Home.aspx");
t = termSet.CreateTerm("HR", 1033);
"http://intranet.contoso.com/hr");
t = termSet.CreateTerm("IT", 1033);
"http://intranet.contoso.com/it");
t = termSet.CreateTerm("Legal", 1033);
"http://intranet.contoso.com/legal");
t = termSet.CreateTerm("Finance", 1033);
"http://intranet.contoso.com/finance");
try
{
}
}
at E:\Labfiles\Starter\Snippets\CreateNavigationTerms.txt.

CreateNavigationTermSet(group, "Intranet");
TermSet s_termSet = group.TermSets["Intranet"];

CreateNavigationTerms(s_termSet);
8. On the Term Store Management Tool page, click Refresh.
9. Expand Navigation, expand Intranet, and notice the terms in your term set.
10. Click the Intranet term set, and on the INTENDED USE tab notice the Use this Term Set for Site
Navigation check box is selected.
11. Click the Finance term, and on the NAVIGATION tab notice the Simple Link or Header option is
selected.
12. Click the Home term, and on the NAVIGATION tab notice that the Term-Driven Page with
Friendly URL option is selected.
13. On the TERM-DRIVEN PAGES tab, notice that the Target Page Settings has been configured to
/Pages/Home.aspx.
 Task 3: Pinning Terms to Navigation Term Sets

t = termSet.CreateTerm("Finance", 1033);
http://intranet.contoso.com/finance");
try
{
}
}

{
L7-5
{
}
}
Note: If you prefer, you can copy the PinTermSet method from the text file at
E:\Labfiles\Starter\Snippets\PinTermSet.txt.

CreateNavigationTermSet(group, "Team");
TermSet t_termSet = group.TermSets["Team"];
PinTermSet(s_termSet, t_termSet);
8. On the Term Store Management Tool page, click Refresh.
9. Expand Navigation, and notice a new Team term set has been created.
10. Expand Team, and notice the same terms exist in the new term set as in the Intranet term set.
 Task 4: Configure and Test Managed Navigation


{
{
}
}
static void SetManagedNavigation(SPSite site, string groupName, string termSetName)

{
Group group = termStore.Groups[groupName];
TermSet termSet = group.TermSets[termSetName];
WebNavigationSettings settings = new WebNavigationSettings(site.RootWeb);
settings.GlobalNavigation.Source = StandardNavigationSource.TaxonomyProvider;
settings.GlobalNavigation.TermStoreId = termStore.Id;
settings.GlobalNavigation.TermSetId = termSet.Id;
settings.Update();
}
Note: If you prefer, you can copy the SetManagedNavigation method from the text file at
E:\Labfiles\Starter\Snippets\SetManagedNavigation.txt.

{
CreateNavigationTermSet(site, group, "Intranet");
CreateNavigationTermSet(group, "Team");
TermSet t_termSet = group.TermSets["Team"];
PinTermSet(s_termSet, t_termSet);
}
5. Replace the located code, with the following code:

{
SetManagedNavigation(site, "Navigation", "Intranet");
}
using (SPSite site = new SPSite("http://team.contoso.com"))
{
try
{
// Activate the publishing feature.
site.Features.Add(Guid.Parse("f6924d36-2fa8-4f0b-b16d-06b7250180fa"));
}
SetManagedNavigation(site, "Navigation", "Team");
}
Note: If you prefer, you can copy the Main method from the text file at
E:\Labfiles\Starter\Snippets\Main.txt.
Explorer.
8. In Internet Explorer, click New Tab, in the address bar, type http://intranet.contoso.com, and then
press Enter. Notice that the managed navigation items are displayed. If the navigation items are not
visible, click Refresh.
9. Click the HR node, and notice that you are directed to the http://intranet.contoso.com/hr URL.
10. Click New Tab, in the address bar, type http://team.contoso.com, and then press Enter. Notice in
the global navigation area that the pinned terms being used are similar to your intranet publishing
site.
Results: A new navigation term set used by a site collection and shared by a team site.
L7-7
Lab B: Publishing Sites for Multiple Devices

Exercise 1: Creating a Device Channel
 Task 1: Create a New Device Channel

4. Under Look and Feel, click Device Channels.
5. On the Device Channels page, click new item.
6. In the Name box, type Windows Phone.
7. In the Alias box, type WindowsPhone.
8. In the Description box, type The Windows Phone mobile channel.
9. In the Device Inclusion Rules textbox, type Windows Phone.

10. Select the Active check box, and then click Save.
 Task 2: Create and Configure a New Device Channel Master Page

3. On the ribbon, on the FILES tab, click Upload Document.
4. In the Add a master page dialog box, click Browse.
5. In the Choose File to Upload dialog box, browse to E:\Labfiles\Starter, click

WindowsPhone.master, and then click Open.
6. In the Add a master page dialog box, click OK.
7. In the Master Page gallery - WindowsPhone.master dialog box, in the Content Type list, click ASP
NET Master Page.
8. In the Compatible UI Version(s) section, select the 15 check box, and then click Save.
9. At the bottom of the page, click the next page arrow.
10. In the WindowsPhone.master drop-down list, click Publish a Major Version.
11. In the Publish Major Version dialog box, click OK.
12. On the Windows Start page, type SharePoint, and then click SharePoint Designer 2013.
14. In the Open Site dialog box, in the Site name box, type http://intranet.contoso.com, and then
click Open.
17. In the Navigation section, click Master Pages.
18. In the middle pane, click WindowsPhone.master.

20. In the WindowsPhone.master file, locate and delete the div element with an id value of siteIcon. Be
sure to delete the opening tag, the closing tag, and everything in between.
22. Close SharePoint Designer and switch back to Internet Explorer.
24. Under Look and Feel, click Master page.
25. In the Windows Phone list, click WindowsPhone, and then click OK.
 Task 3: Test the Device Channel and Master Page

1. In Internet Explorer, click the site icon to return to the home page, and then press F12.
2. In F12 Developer Tools, on the Tools menu, point to Change user agent string, and then click
Custom.
3. In the Custom User Agent Strings dialog box, in the Friendly Name box, type Windows Phone.
4. In the User Agent String box, type Windows Phone, and then click Add.
5. In the Custom User Agent Strings dialog box, click Set.
6. Reload the page, and notice that the site icon is no longer displayed.
7. Close F12 Developer Tools and close Internet Explorer.
Results: After completing this exercise, you should have configured a device channel for Windows Phone
devices.
Exercise 2: Using Device Channel Panels

 Task 1: Add a New Device Channel Panel
5. On the FILES menu, click Upload Document.
6. In the Add a master page dialog box, click Browse.
7. In the Choose File to Upload dialog box, browse to E:\Labfiles\Starter, click custom.master, and
then click Open.
8. In the Add a master page dialog box, click OK.
9. In the Master Page gallery - custom.master dialog box, in the Content Type list, click ASP NET
Master Page.
10. In the Compatible UI Version(s) section, select the 15 check box, and then click Save.
11. In the custom.master drop-down list, click Publish a Major Version.
12. In the Publish Major Version dialog box, click OK.

L7-9
14. In the Navigation section, click Master Pages.
15. In the middle pane, click custom.master. If the custom.master file is not visible, click Refresh.
17. In the custom.master file, locate the following code:
<%@ Register TagPrefix="wssuc" TagName="Welcome"

src="~/_controltemplates/15/Welcome.ascx" %>
18. On a new line below the located code, add the following code:
<%@ Register TagPrefix="PublishingWebControls"

Namespace="Microsoft.SharePoint.Publishing.WebControls"
Assembly="Microsoft.SharePoint.Publishing, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" %>
Note: You can copy the Register directive from the text file at
E:\Labfiles\Starter\Snippets\PublishingWebControlsTagPrefix.txt.
<a id="mainContent" name="mainContent" tabindex="-1"></a>
20. On a new line immediately below the located code, add the following code:
<PublishingWebControls:DeviceChannelPanel runat="server" ID="mpanelwindowsphone1"

IncludedChannels="WindowsPhone">
Welcome Windows Phone User!
</PublishingWebControls:DeviceChannelPanel>
Note: If you prefer, you can copy the DeviceChannelPanel element from the text file at
E:\Labfiles\Starter\Snippets\DeviceChannelPanel.txt.
21. On the Quick Access toolbar, click Save.

24. Under Look and Feel, click Master page.
25. In the Windows Phone list, click custom.
26. In the Default list, click custom.
27. In the All Channels list, click custom, and then click OK.
 Task 2: Test the Device Channel Panel

1. In Internet Explorer, click the site icon to return to the home page. Verify that the page renders
normally.
2. Press F12.
3. In F12 Developer Tools, on the Tools menu, point to Change user agent string, and then click
Windows Phone.
4. Reload the page, and notice that the page now includes a welcome message for Windows Phone
users.
Results: After completing this exercise, you should have configured a master page to use device channel
panels to display content to users of specific devices.
L8-1
Module 8: Developing Optimized Internet Sites

Lab: Optimizing SharePoint Publishing Sites
Exercise 1: Optimizing a Site for Search Engines
 Task 1: Configure SEO Settings
3. On the Windows Start screen, type Visual Studio, and then click Visual Studio 2012.
5. In the Open Project dialog box, browse to E:\Labfiles\Starter\Contoso.Website.SEO, click

Contoso.Website.SEO.sln, and then click Open.
6. In Solution Explorer, right-click the Features folder, and then click Add Feature.
7. Right-click Feature1, and click Rename.
8. Type Settings, and press Enter.
9. In Designer, in the Title box, type Contoso.Website.SEO - Settings.

11. In Solution Explorer, right-click Settings, and then click Add Event Receiver.
12. In the Settings.EventReceiver.cs file, add the following using statements:
using System.Text;
13. Select the following code, and then click the Uncomment the selected lines button:
//public override void FeatureActivated(SPFeatureReceiverProperties properties)

//{
//}

{
SPSite site = (SPSite) properties.Feature.Parent;

{
}
Best Practice: When calling the SPSite.RootWeb property, it is a best practice to utilize a
using statement to ensure the object instance is properly disposed of when complete.
For the remainder of this Lab, code should be appended within the using statement curly braces.
16. Click on the blank line between the two curly brackets.
17. On the EDIT menu, click Insert File as Text.
18. In the Insert File dialog box, in the file type dropdown list, click All Files (*.*).
19. Browse to E:\Labfiles\Starter\Snippets, click ConfigureSEOSettings.txt, and then click Open.
a. It enables the sitemap generation feature.
b. It configures the robots.txt file to exclude various file paths from search crawling.
c. It adds Bing web identification meta tags to all pages.
d. It enables canonical URLs for the Product Catalog pages.

21. On the BUILD menu, click Build Solution.
22. Verify that the build completes without errors.
 Task 2: Configure SEO Properties

2. Right-click Feature1, and then click Rename.
3. Type Props, and press Enter.
4. In Designer, in the Title box, type Contoso.Website.SEO - Props.

6. In Solution Explorer, right-click the Props feature, and then click Add Event Receiver.
7. In the Props.EventReceiver.cs file, add the following using statements:
using Microsoft.SharePoint.Utilities;

//{
//}

{
SPSite site = (SPSite) properties.Feature.Parent;

{
}
11. Click on the blank line between the two curly brackets.
12. On the EDIT menu, click Insert File as Text.
14. Browse to E:\Labfiles\Starter\Snippets, click ConfigureSEOProperties.txt, and then click Open.

L8-3
a. It updates the welcome page with SEO properties.
b. It adds custom SEO properties to the Navigation term set.
 Task 3: Test the SEO Settings and Properties Features

1. In Visual Studio, on the DEBUG menu, click Start Without Debugging.
4. Under Site Collection Administration, click Site collection features.
5. On the Site Collection Features page, on the Search Engine Sitemap feature, click Activate.
6. On the Contoso.Website.SEO - Props feature, click Activate
7. On the Contoso.Website.SEO - Settings feature, click Activate
8. Click the Back to Site Settings button.

9. Under Site Collection Administration, click Search engine optimization settings.
10. In the Verify ownership of this site with search engines section, verify that the meta tag with the
name msvalidate.01 has been added.
11. In the Consolidate link popularity with canonical URLs section, verify that the Filter link
parameters box contains category, and then click OK.
12. Under Site Collection Administration, click Search Engine Sitemap Settings.
13. On the Search Engine Sitemap page, verify that the text box contains Disallow: /legal/, and then
click OK.
14. In the address bar, type http://www.contoso.com, and then press Enter.
15. Click the Settings icon, and then click Edit Page.
16. On the Contoso Pharmaceuticals page, on the PAGE menu, click Edit Properties, and then click
Edit SEO Properties.
17. Verify that the SEO properties have been updated and are not blank, and then click Cancel.
18. On the PAGE menu, click Check In, and then click Discard Check Out.
for search engine optimizations should be complete.
Exercise 2: Maximizing the Performance of a Publishing Site

 Task 1: Configure BLOB Caching
1. On the Windows Start screen, type Visual Studio, and then click Visual Studio 2012.
3. In the Open Project dialog box, browse to E:\Labfiles\Starter\Contoso.Website.Perf, click

Contoso.Website.Perf.sln, and then click Open.

6. Type BlobCache, and then press Enter.
7. In Designer, in the Title box, type Contoso.Website.Perf - BLOB Cache.
8. In the Scope list, click WebApplication.

9. In Solution Explorer, right-click the BlobCache feature, and then click Add Event Receiver.
10. In the BlobCache.EventReceiver.cs file, add the following using statements:
using Microsoft.SharePoint.Administration;

//{
//}
12. In the FeatureActivated method, add a new line between the curly brackets, and then on the
EDIT menu, click Insert File as Text.
14. Browse to E:\Labfiles\Starter\Snippets, click ConfigureBlobCache.txt, and then click Open.

a. It modifies the web.config file for the web application to enable the BLOB cache.
b. It changes the maximum size of the BLOB cache on disk to 5GB.
 Task 2: Configure Page Output Caching

3. Type OutputCache, and then press Enter.

4. In Designer, in the Title box, type Contoso.Website.Perf - OutputCache.
6. In Solution Explorer, right-click the OutputCache feature, and then click Add Event Receiver.
L8-5
7. In the OutputCache.EventReceiver.cs file, add the following using statements:

//{
//}
9. In the FeatureActivated method, add a new line between the curly brackets, and then on the EDIT
menu, click Insert File as Text.
11. Browse to E:\Labfiles\Starter\Snippets, click ConfigureOutputCache.txt, and then click Open.
a. It creates a new cache profile on the publishing web.
b. It enables and configures the page output cache settings for the site collection.
 Task 3: Configure Image Renditions

3. Type ImageRenditions, and then press Enter.
4. In Designer, in the Title box, type Contoso.Website.Perf - Image Renditions.
6. In Solution Explorer, right-click the ImageRenditions feature, and then click Add Event Receiver.
7. In the ImageRenditions.EventReceiver.cs file, add the following using statements:
using System.Linq;
using System.Linq.Expressions;

//{
//}
9. In the FeatureActivated method, add a new line between the curly brackets, and then on the EDIT
menu, click Insert File as Text.
11. Browse to E:\Labfiles\Starter\Snippets, click ConfigureImageRenditions.txt, and then click Open.
a. It creates a new image rendition named Masthead.

b. It adds the new image rendition to the collection of image renditions on the root web.
16. Right-click Contoso.Website.Perf, and then click Deploy.
 Task 4: Test the Performance Features

1. On the Windows Start screen, type Central Administration, and then click SharePoint 2013 Central
Administration.
2. On the Central Administration web site, under Application Management, click Manage web
applications.
3. On the Web Applications Management page, click Host Named Site Collection (HNSC) Host
Web Application, and then on the ribbon, click Manage Features.
4. In the Manage Web Application Features dialog box, ensure that the Contoso.Website.Perf –
BLOB Cache feature is Active. If it is not Active, click Activate.
5. In the Manage Web Application Features dialog box, click OK.

7. On the Windows Start screen, click Computer.
8. In File Explorer, browse to C:\inetpub\wwwroot\wss\VirtualDirectories\80.
9. Right-click web.config, point to Open with, and then click Microsoft Visual Studio 2012.
10. In Visual Studio, on the EDIT menu, point to Find and Replace, and then click Quick Find.
11. In the Quick Find box, type BlobCache, and press Enter.
12. Validate that the <BlobCache> element has been updated and that the Enabled attribute has been
set to true.
13. Close Visual Studio 2012, and then close File Explorer.
15. In Internet Explorer, in the address bar, type http://www.contoso.com, and then press Enter.
18. Under Site Collection Administration, click Site collection output cache.
19. On the Output Cache Settings page, verify the Enable output cache check box is selected.
20. Verify the Anonymous Cache Profile is set to Contoso Anonymous.
21. Verify the Authenticated Cache Profile is set to Disabled, and then click Cancel.
22. Under Look and Feel, click Image Renditions.
23. On the Image Renditions page, verify that a Masthead rendition has been created.
will be configured for performance optimizations.
L9-1
Module 9: Working with Business Connectivity Services

Lab: Working with Business Connectivity
Services
Exercise 1: Creating Farm-Scoped External Content Types
 Task 1: Configure SQL Server and the Secure Store Service to Manage Authentication
for BCS
1. On the Start screen, type SQL, and then click SQL Server Management Studio.
3. In Object Explorer, expand Security, expand Logins, and then double-click

4. In the Login Properties - CONTOSO\Administrator dialog box, under Select a page, click User
Mapping.
5. Under Users mapped to this login, in the Map column, confirm that the ContosoRetailDW check
box is selected.
6. Under Database role membership for: ContosoRetailDW, confirm that db_datareader is selected.
Note: If ContosoRetailDW and db_datareader are not selected, select them now.
7. Click OK, and then close SQL Server Management Studio.
8. On the Start screen, type SharePoint, and then click SharePoint 2013 Central Administration.

10. On the list of service applications, click Contoso Secure Store Service Application.
11. On the ribbon, in the Manage Target Applications group, click New.
12. On the Create New Secure Store Target Application page, in the Target Application ID box, type
ContosoDWGeographyApp.
13. In the Display Name box, type Contoso Retail Geography Data Warehouse.

15. In the Target Application Type list, click Group, and then click Next.
16. Leave the Field Name and Field Type unchanged, and then click Next.
17. In the Target Application Administrators box, type CONTOSO\Administrator.
18. In the Members box, type Everyone, and then click OK.
Note: You have created a group target application that maps all users to a single set of
credentials. You will now set the credentials that the target application will use to connect to the
external database.
19. In the list of target applications, select the ContosoDWGeographyApp check box.
20. On the ribbon, in the Credentials group, click Set.
21. In the Set Credentials for Secure Store Target Application (Group) dialog box, in the Windows
User Name box, type CONTOSO\Administrator.
22. In the Windows Password, and Confirm Windows Password boxes, type Pa$$w0rd, and then click
OK.
 Task 2: Create the Geography ECT

1. On the Start screen, type SharePoint, and then click SharePoint Designer 2013.
click Open.
Note: SharePoint Designer may take some time to open the site.
5. When SharePoint Designer has finished loading the site, in the Navigation pane, click External
Content Types.
7. In the External Content Type Information pane, in the Name row, click New external content
type.
8. Type Geography, and then press Tab.
9. In the External System row, click Click here to discover external data sources.

11. In the External Data Source Type Selection dialog box, in the Data Source Type list, click SQL
Server, and then click OK.
12. In the SQL Server Connection dialog box, in the Database Server box, type LONDON.
14. In the Name (optional) box, type ContosoRetailDWConnection.
15. Click Connect with Impersonated Windows Identity.
16. In the Secure Store Application ID box, type ContosoDWGeographyApp, and then click OK.
17. In the BCS Secure Store : ContosoDWGeographyApp dialog box, log in as

CONTOSO\Administrator with password Pa$$w0rd, and then click OK.
18. On the Data Source Explorer tab, expand ContosoRetailDWConnection, and then expand Tables.
19. In the Microsoft SharePoint Designer dialog box, click OK.
20. Right-click DimGeography, and then click Create All Operations.
21. In the All operations dialog box, on the Operation Properties page, click Next.
22. On the Parameters Configuration page, in the Data Source Elements list, clear the ETLLoadID,
LoadDate, and UpdateDate check boxes.
23. Click GeographyKey, and confirm that Map to Identifier is selected.
24. Click ContinentName, and then select the Show In Picker check box.
L9-3
25. Click CityName, and then select the Show In Picker check box.
26. Click StateProvinceName, and then select the Show In Picker check box.
27. Click RegionCountryName, select the Show In Picker check box, and then click Next.
28. On the Filter Parameters Configuration page, click Finish.
Note: Having created an external content type, you will now create an external list to display data
from the external content type
29. On the ribbon, in the Lists & Forms group, click Create Lists & Form.
30. In the Save Confirmation dialog box, click Yes.
31. In the Create List and Form for Geography dialog box, in the List Name box, type Regions, and
then click OK.
32. On the ribbon, in the Views group, click Summary View.
33. Locate the External Lists pane, and observe that it now includes a list named Regions.
37. In the list of service applications, on the Business Data Connectivity Service Application row, click
Contoso Business Data Connectivity Service Application.
38. On the ribbon, in the Permissions group, click Set Metadata Store Permissions.
39. In the Set Metadata Store Permissions dialog box, type Domain Admins, and then click Add.
40. Under Permissions for CONTOSO\domain admins, select all the check boxes.
41. Select the Propagate permissions to all BDC Models, External Systems and External Content
Types in the BDC Metadata Store check box, and then click OK.
42. In the list of external content types, select the Geography check box.
43. On the ribbon, in the Permissions group, click Set Object Permissions.
45. Under Permissions for Everyone, select the Execute, and Selectable In Clients check boxes, and
then click OK.
46. In the Address bar, type http://sharepoint.contoso.com, and then press Enter.
47. On the Contoso SharePoint Site page, on the Quick Launch menu, click Regions.
Verify that the Regions list retrieves and displays a set of data from the external database.
 Task 3: Configure a Filter for the Geography ECT

2. Under Recent Sites, click http://sharepoint.contoso.com/.
3. In the Navigation pane, click External Content Types, and then click Geography.
4. In the External Content Type Operations list, double-click Read List.

6. In the Read List dialog box, on the Operation Properties page, click Next.
8. In the Properties pane, in the Data Source Element list, click RegionCountryName.
9. To the right of Filter, click Click to Add.
10. In the Filter Configuration dialog box, in the New Filter box, type By Country.
11. Confirm that the Filter Type list is set to Comparison, and the Operator list is set to Equals.
12. In the Filter Field list, click RegionCountryName.
13. Select the Use to create match list in external item picker check box, and then click OK.
14. On the Filter Parameters Configuration page, in the Default Value list, type United States, and
then click Finish.
15. On the FILE menu, click Save.

18. In the Address bar, type http://sharepoint.contoso.com, and then press Enter.
19. On the Quick Launch menu, under Lists, click Regions. You should now be able to see a list of
regions in the United States.
20. On the LIST menu, in the Manage Views section, click Modify View.
21. On the Edit View page, in the Data Source Filters section, in the Filter Value box, type China, and
then click OK.
Observe that the Regions list now displays a list of States/Provinces in China.
 Task 4: Create the Customer ECT

1. On the Start screen, type SharePoint, and click SharePoint Designer 2013.
click Open.
4. In the Site Objects pane, click External Content Types.
5. On the ribbon, in the New section, click External Content Type.
6. On the New external content type tab, in the External Content Type Information pane, to the
right of Name, click New external content type.
7. Type Customer, then press Tab.
8. To the right of External System, click Click here to discover external data sources and define
operations.
11. On the Data Source Explorer tab, right-click DimCustomer, and then click New Read Item
Operation.
12. In the Read Item dialog box, on the Operations Properties page, in the Operation Name box, type
ReadCustomer.
13. In the Operation Display Name box, type Read Single Customer, and then click Next.
L9-5
14. On the Input Parameters Configuration page, click CustomerKey, confirm that the Map to
Identifier check box is selected, and then click Next.
15. On the Return Parameter Configuration page, clear all check boxes except:
a. CustomerKey
b. GeographyKey
c. Title
d. FirstName
e. LastName
f. EmailAddress
16. Click CustomerKey, confirm that the Map to Identifier check box is selected, and then click Finish.
17. On the Data Source Explorer tab, right-click DimCustomer, and then click New Read List
Operation.
18. In the Read List dialog box, on the Operations Properties page, in the Operation Name box, type
ReadCustomerList.
19. In the Operation Display Name box, type Read Customer List, and then click Next.
21. In the Properties pane, to the right of Filter, click Click to Add.
22. In the Filter Configuration dialog box, in the New Filter box, type Results Limit.
23. In the Filter Type drop-down list box, click Limit, and then click OK.
24. On the Filter Parameters Configuration page, in the Default Value list, type 100, and then click
Next.
25. On the Return Parameter Configuration page, clear all check boxes except:
a. CustomerKey
b. GeographyKey
c. Title
d. FirstName
e. LastName
f. EmailAddress
26. Click CustomerKey, and confirm that the Map to Identifier check box is selected.
27. Click FirstName, and then select the Show In Picker check box.
28. Click LastName, select the Show In Picker check box, and then click Finish.

30. On the ribbon, in the Lists & Forms section, click Create Lists & Form.
31. In the Create List and Form for Customer dialog box, in the List Name box, type Customers, and
then click OK.
32. On the ribbon, in the Views section, click Summary View.
33. Under External Lists, notice the new Customers list.

36. In Internet Explorer, in the Address bar, type http://sharepoint.contoso.com,and then press Enter.
37. On the Quick Launch menu, click Customers, and verify that the list displays customer data.
 Task 5: Create an Association

click Open.
4. In the Navigation pane, click External Content Types, and then click Customer.
5. On the ribbon, in the Views section, click Operations Design View.

8. Right-click DimCustomer, and click New Association.

9. In the Association dialog box, on the Association Properties page, in the Association Name box,
type CustomerGeographyNavigation.
10. In the Association Display Name box, type Customer Geography Navigation, and then in the
Related External Content Type pane, click Browse.
11. In the External Content Type Selection dialog box, click Geography, and then click OK.
12. On the Association Properties page, in the Field list, ensure that GeographyKey is selected, and
then click Next.
13. On the Input Parameters Configuration page, in the Data Source Elements list, click
GeographyKey.
14. In the Properties pane, select the Map to Identifier check box, and then click Next.
15. On the Filter Parameters Configuration page, click Next.
16. On the Return Parameter Configuration page, clear all the check boxes except:
a. CustomerKey
b. GeographyKey
c. Title
d. FirstName
e. LastName
f. EmailAddress
17. Click CustomerKey, and ensure that Map to Identifier is selected.
18. Click Finish.

L9-7
22. In Internet Explorer, in the Address bar, type http://sharepoint.contoso.com, and then press Enter.
23. On the Quick Launch menu, click Site Contents.
24. On the Site Contents page, click Site Pages.
25. On the ribbon, on the FILES tab, in the New group, click the New Document drop-down arrow, and
then click Web Part Page.
26. On the New Web Part Page page, in the Name box, type CustomersByCountry, and then click
Create.
27. On the new page, in the Left Column section, click Add a Web Part.
28. In the Categories list, click Business Data.
29. In the Parts list, click Business Data List, and then click Add.
30. In the Left Column section, in the Business Data List section, click Open the tool pane.
31. In the Business Data List tool pane, to the right of the Type box, click the Select External Content
Type icon.
32. In the External Content Type Picker, click Geography, and then click OK.
Note: It may take some time to populate the External Content Type Picker dialog box.
33. In the Business Data List tool pane, click Apply.

When the page has refreshed, notice that the By Country filter is now available in the web part.
34. In the Geography List web part, in the text box for the By Country filter, type Australia, and then
click Retrieve Data.
35. On the new page, in the Middle Column section, click Add a Web Part.
36. In the Categories list, click Business Data.
37. In the Parts list, click Business Data Related List, and then click Add.
38. In the Middle Column section, in the Business Data Related List web part, click Open the tool
pane.
39. In the Business Data Related List tool pane, to the right of the Type box, click the Select External
Content Type icon.
40. In the External Content Type Picker dialog box, click Customer, and then click OK.
41. In the Business Data Related List tool pane, notice the Relationship dropdown list showing the
value Default (Customer Geography Navigation) association.
42. In the Tool pane, click Apply and wait for the page to refresh.
43. In the Customer List web part, move the mouse just above the Edit View link until a black drop-
down arrow appears.
44. Click the Customer List Web Part Menu drop-down arrow, point to Connections, point to Get
Related Item From, and then click Geography List.
45. On the ribbon, click Stop Editing.
46. In the Geography List, click the double-arrow icon next to GeographyKey 425. Notice that the
Customer List web part updates to show a list of customers for that region.

Results: After this exercise, you should have created two external content types named Geography and
Customer, exposed their data by using external lists and business data web parts.
Exercise 2: Creating App-Scoped External Content Types

2. In File Explorer, browse to E:\Labfiles\Starter\ContosoODataService, double-click

ContosoODataService.sln.
4. In Visual Studio, in Solution Explorer, double-click ContosoODataWebService.svc.
5. Review the InitializeService method. Notice that this method exposes the DimProducts,
DimProductCategories and DimProductSubcategories entities. These map to the DimProduct,
DimProductCategory and DimProductSubcategory database tables.
6. On the DEBUG menu, click Start Without Debugging. Leave the service running because it is
required in the following tasks.

1. On the Task bar, right-click Visual Studio, and then click Visual Studio 2012.
2. On the Start page, click New Project.

3. Under Templates, expand Visual C#, expand Office/SharePoint, and then click Apps.
4. In the templates list, click App for SharePoint 2013.
5. In the Name box, type ContosoOData.

debugging your app, type http://dev.contoso.com/.
click Finish.
9. In Solution Explorer, right-click the ContosoOData project, point to Add, and then click Content
Types for an External Data Source.
10. In the SharePoint Customization Wizard, in the What OData service URL do you want to use to
create the external data source box, type
http://localhost:12345/ContosoODataWebService.svc/.
11. In the What do you want to name your new data source box, type ContosoODataSource, and
then click Next.
12. On the Select the Data Entities page, select the DimProducts and DimProductSubcatergories
check boxes.
13. Ensure that the Create list instances for the selected data entities (except Service Operations)
check box is selected, and then click Finish.
L9-9
14. In Solution Explorer, double click DimProducts.ect.

Notice the list of columns and at the bottom of the page notice the use of a Limit filter.
15. In Solution Explorer, right click DimProducts.ect, and then click Open With.
16. In the Open With - DimProducts.ect dialog box, click XML (Text) Editor, and then click OK.

18. On the EDIT menu, point to Find and Replace, and then click Quick Find.
19. In the Search term box, type <Association. In the code, note that the highlighted Association
element contains SourceEntity and DestinationEntity elements that map the DimProducts entity
to the DimProductsSubcategories entity.
20. In Solution Explorer, double-click DimProducts.
21. In the List URL box, type Lists/Products.
22. In Solution Explorer, under DimProducts, double-click Elements.xml.

25. Notice the DataSource element in the XML file that points to the external system.
 Task 3: Interacting with Business Data by Using External Lists

1. In Solution Explorer, double click AppManifest.xml.
2. On the AppManifest.xml page, in the Start page box, type ContosoOData/Lists/Products.

4. If SharePoint displays an error message, close Internet Explorer, and then in Visual Studio, on the
DEBUG menu, click Start Debugging.
5. In Internet Explorer, in the DimProducts list, in the ProductKey column, click 1.
6. On the ribbon, click Edit Item.
7. In the ProductDescription box, type New description, and then click Save.
9. On the Start screen, type SQL, and then click SQL Server Management Studio.
11. In Object Explorer, expand Databases, expand ContosoRetailDW, and then expand Tables.
12. Right-click dbo.DimProduct, and then click Select Top 1000 Rows.
13. Verify that the ProductDescription for row 1 has been updated to New description.
Results: After this exercise, you should have created two app-scoped external content types named
Product and Category by using an OData connection.
L10-1
Module 10: Creating Advanced Business Data Connectivity

Models
Lab: Creating and Deploying a .NET
Connectivity Assembly
Exercise 1: Create a .NET Connectivity Assembly
 Task 1: Use Visual Studio to Create New BDC Model
password Pa$$w0rd.
3. On the Start page, type Visual Studio, and then click Visual Studio 2012.
5. In the New Project dialog box, under Templates, expand Visual C#, and then click
Office/SharePoint.
6. In the list of templates, click SharePoint 2013 - Empty Project.
7. In the Name box, type NorthwindModel.
9. In the SharePoint Customization Wizard dialog box, in the What site do you want to use for
debugging box, type http://dev.contoso.com.
10. Click Deploy as a farm solution, and then click Finish.

11. In Solution Explorer, right-click NorthwindModel, point to Add, and then click New Item.
12. In the Add New Item - NorthwindModel dialog box, in the Office/SharePoint category, click
Business Data Connectivity Model.
13. In the Name box, type NorthwindModel, and then click Add.
 Task 2: Define Entity Properties

1. In the NorthwindModel.bdcm window, double-click the Entity1 text, and then type Product.
2. Click the Identifier1 identifier.

3. In Properties, in the Name box, type ProductId.
4. In the Type Name list, click System.Int32.
5. In Solution Explorer, under NorthwindModel, right-click Entity1.cs, and then click Rename.
6. Type Product, and then press Enter.
8. In Solution Explorer, double-click Product.cs.

9. In the Product.cs file, in the Product class, replace the existing code, with the following code:
// Properties in first database

public int ProductId { get; set; }
public string Name { get; set; }
public string Description { get; set; }
public string RetailPrice { get; set; }
public string QuantityPerUnit { get; set; }
// Properties in second database
public string ProductManager { get; set; }
public string Manufacturer { get; set; }
public string CostBasis { get; set; }
 Task 3: Define Entity Methods

1. Switch to the NorthwindModel.bdcm tab.
2. In BDC Explorer, expand NorthwindModel, expand NorthwindModel, expand Product, expand

ReadItem, expand id, and then click Identifier1.
3. In Properties, in the Name box, type ProductId, and then press Enter.
4. In the Type Name list, click Int32.
5. In BDC Explorer, under ReadItem, expand returnParamater, and then click Entity1.
6. In Properties, confirm the Type Name property is set to

NorthwindModel.NorthwindModel.Product, NorthwindModel.
7. In the Name box, type Product, and then press Enter.
8. In BDC Explorer, under returnParamater, expand Product, and then click Identifier1.
9. In Properties, in the Name box, type ProductId, and then press Enter.
10. Set the Read-only property to True.
11. Set the Type Name property to System.Int32.

12. In BDC Explorer, under Product, click Message.
13. In Properties, in the Name box, type Name, and then press Enter.
14. In BDC Explorer, under returnParameter, right-click Product, and then click Add Type Descriptor.
15. In Properties, in the Name box, type Description, and then press Enter.
16. Repeat steps 14 and 15 for the following:
o RetailPrice
o QuantityPerUnit
o ProductManager
o Manufacturer
o CostBasis
17. In BDC Explorer, expand ReadList, expand returnParamater, and then click Entity1List.
18. In Properties, Confirm that the Type Name property is set to

System.Collections.Generic.IEnumerable`1[[NorthwindModel.NorthwindModel.Product,
NorthwindModel]]
19. In the Name box, type Products, and then press Enter.
20. In BDC Explorer, expand Products, and then click Entity1.
L10-3
21. In Properties, in the Name box, type Product, and then press Enter.
22. In Properties, confirm that the Type Name property is set to

NorthwindModel.NorthwindModel.Product, NorthwindModel.
23. In Solution Explorer, right-click NorthwindModel.bdcm, and then click Open With.
24. In the Save File dialog box, click Yes.

25. In the Open With - NorthwindModel.bdcm dialog box, click XML (Text) Editor, and then click OK.
27. In the NorthwindModel.bdcm file, select the following code, and then press CTRL+C:
<TypeDescriptor TypeName="System.Int32" IdentifierName="ProductId" Name="ProductId"

ReadOnly="true" />
<TypeDescriptor TypeName="System.String" Name="Name" />

<TypeDescriptor Name="Description" TypeName="System.String"/>
<TypeDescriptor Name="RetailPrice" TypeName="System.String"/>
<TypeDescriptor Name="QuantityPerUnit" TypeName="System.String"/>
<TypeDescriptor Name="ProductManager" TypeName="System.String"/>
<TypeDescriptor Name="Manufacturer" TypeName="System.String"/>
<TypeDescriptor Name="CostBasis" TypeName="System.String"/>
28. Select the following lines of code, and then press CTRL+V:
<TypeDescriptor TypeName="System.String" IdentifierName="ProductId"

Name="Identifier1" />
<TypeDescriptor TypeName="System.String" Name="Name" />

29. In the Methods element, before the closing tag, press Enter.

Files (*.txt).
32. Click MethodDefinitions.txt, and then click Open.
33. Review the method definitions you have just added to the model.
34. Click Save All.
 Task 4: Implement Entity Methods

1. Right-click the NorthwindModel project, and then click Add Reference.
2. In the Reference Manager - NorthwindModel dialog box, click Browse.
3. In the Select the files to reference dialog box, browse to

C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.Office.SecureStoreService\v4.0_15.
0.0.0__71e9bce111e9429c, click Microsoft.Office.SecureStoreService.dll, and then click Add.
5. In the Select the files to reference dialog box, browse to

C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Microsoft.Office.SecureStoreService.Server.S
ecurity\v4.0_15.0.0.0__71e9bce111e9429c, click
Microsoft.Office.SecureStoreService.Server.Security.dll, and then click Add.

7. In the Select the files to reference dialog box, browse to C:\Program Files\Common
Files\Microsoft Shared\Web Server Extensions\15\ISAPI, click Microsoft.BusinessData.dll, and
then click Add.
8. Click Assemblies, select the System.Web check box, and then click OK.
9. In Solution Explorer, double-click ProductService.cs, and after the existing using statements, press
Enter.
Files (*.txt).
12. Click UsingStatements.txt, and then click Open.
13. Delete the existing ReadItem method.
14. Delete the existing ReadList method.
15. In the ProductServices.cs, file, at the end of the ProductService class, before the closing brace, press
Enter.
Files (*.txt).
18. Click EntityMethods.txt, and then click Open.
19. Review the code you have just added to the code file.
20. Click Save All.
 Task 5: Set Up Secure Store Authentication

1. Modify the class declaration to match the code below:
public class ProductService : IContextProperty
2. At the beginning of the ProductService class, after the opening brace, press Enter.
3. Add the following class variables and properties to implement the IContextProperty interface:
public static string username = "";

public static string password = "";
public IExecutionContext ExecutionContext { get; set; }
public ILobSystemInstance LobSystemInstance { get; set; }
public IMethodInstance MethodInstance { get; set; }
4. In the ProductService class, after the last of the property declarations, press Enter.

Files (*.txt).
7. Click SecureStoreCode.txt, and then click Open.
Administration.
10. Click Secure Store Service.

L10-5
11. On the ribbon, in the Manage Target Applications section, click New.
12. On the Create New Secure Store Target Application page, in the Target Application ID box, type
Northwind.
13. In the Display Name box, type Northwind.

15. In the Target Application Type list, click Group, and then click Next.
16. On the Create New Secure Store Target Application page, change the Field Name to User Name
and Password by removing the Windows text.
17. Change the Field Type to User Name and Password, and then click Next.
18. On the Create New Secure Store Target Application page, in the Target Application
Administrators box, type CONTOSO\administrator, and then click Check Names.
19. In the Members box, type CONTOSO\domain users, click Check Names, and then click OK.
20. Select the Northwind check box.
21. On the ribbon, in the Credentials section, click Set.

22. In the Set Credentials for Secure Store Target Application (Group) dialog box, in the User Name
box, type sqluser.
23. In the Password and Confirm Password boxed, type Pa$$w0rd, and then click OK.
25. In the NorthwindModel.bdcm file, modify the LobSystemInstance xml node by adding the AppId
property, as shown in bold:
<LobSystemInstance Name="NorthwindModel">
<Properties>
<Property Name="AppId" Type="System.String">Northwind</Property>
</Properties>
26. Click Save All.
 Task 6: Configure the Model for Search

1. In the NorthwindModel.bdcm file, locate the following code:
<Properties>
<Property Name="AppId" Type="System.String">Northwind</Property>
2. On a new line after the code, type the following code:
<Property Name="ShowInSearchUI" Type="System.String">x</Property>
<Method Name="ReadItem">
4. On a new line after the code, type the following code:
<Properties>
<Property Name="RootFinder" Type="System.String">Empty</Property>
</Properties>
Results: A .NET connectivity search connector model.
Exercise 2: Deploying and Testing a .NET Connectivity Model

 Task 1: Deploy the .NET Connectivity Solution
1. In solution explorer, under the Package node, click the NorthwindModel node.
2. In Properties, in the Feature Properties property, click the ellipses.
3. In the Feature Properties dialog box, click Add.
4. In the Key box, type SiteUrl.

5. In the Value box, type http://team.contoso.com, and then click OK.
6. In Solution Explorer, expand Features, and then double-click Feature1.
7. In Properties, set the Always Force Install property to True.
8. In Solution Explorer, right-click the NorthwindModel project, and then click Deploy.
9. When the solution has been deployed successfully, switch to SharePoint Central Administration.
10. On the Quick launch menu, under Central Administration, click System Settings.
11. Under Farm Management, click Manage farm features.
12. On the Manage Farm Features page, confirm that the NorthwindModel Feature1 is activated.
13. Use File Explorer to browse to E:\Labfiles\Starter.

14. Right-click DeploySearchConnector.ps1, and then click Run with PowerShell.
15. At the command prompt type Y, and then press Enter.
16. Switch to SharePoint Central Administration.
17. On the Quick Launch menu, under Central Administration, click Application Management.
18. On the Application Management page, under Service Applications, click Manage service
applications.
20. Select the Product check box, and then on the ribbon, click Set Object Permissions.
21. In the Set Object Permissions dialog box, type CONTOSO\domain users, and then click Add.
22. In the Permissions for CONTOSO\domain users section, select all the check boxes, and then click
OK.
L10-7
Note: If you discover an error after deploying the search connector, you must retract the
solution by using Visual Studio (to retract the solution, right-click the project and then click
Retract), and then restart IIS before you can re-deploy the solution. If you do not restart IIS after
the retraction, SharePoint will use the previous version of the assembly and you will get
unexpected results.
 Task 2: Test the .NET Connectivity Solution by Using a BCS Web Part
1. Open a new browser tab, and in the address bar, type http://team.contoso.com, and then press
Enter.
2. Click the Settings icon, and then click Add a page.
3. In the Add a page dialog box, in the New page name box, type Product, and then click Create.
4. On the ribbon, on the INSERT tab, click Web Part.
5. In the Categories section, click Business Data.

6. In the Parts section, click Business Data List, and then click Add.
7. Click the Open the tool pane link.
8. Next to the Type property, click the Select External Content Type icon.
9. In the External Content Type Picker dialog box, click NorthwindModel, and then click OK.
10. In the Business Data List web part properties, click OK.

The page should display product data in the web part.
 Task 3: Test the .NET Connectivity Solution by Using an External List

1. On the Quick Launch menu, click Site Contents.
2. On the Site Contents page, click add an app.

4. In the Adding External List dialog box, in the Name box, type Product.
5. Next to External Content Type, click the Select External Content Type icon.
6. In the External Content Type Picker dialog box, click NorthwindModel, and then click OK.
8. On the Site Contents page, on the Quick Launch menu, click Product. You should see the data
displayed in the external list app.
9. Click new item.
10. On the Product – New Item page, in the Name box type Test.
11. In the Description box type Test description.
12. In the RetailPrice box, type 26.50.
13. In the QuantityPerUnit box, type 12.
14. In the Manufacturer box, type Contoso, and then click Save.
15. At the bottom of the page, in the paging controls, click the right arrow. Repeat this step until you
reach the last page.
16. Verify that the Test product appears in the list.

 Task 4: Set Up BDC Search

1. Switch to SharePoint 2013 Central Administration.
3. Under Service Applications, click Manage service applications.
5. Select the Product check box, and then on the ribbon, click Configure.
6. In the Configure External Content Type Profile Page Host dialog box, in the text box, type
http://team.contoso.com, and then click OK.
8. Under Service Applications, click Manage service applications
10. On the Quick Launch menu, under Crawling, click Content Sources.
11. On the Manage Content Sources page, click New Content Source.
12. On the Add Content Source page, in the Name box, type Northwind.
13. In the Content Source Type section, click Line of Business Data.
14. In the External Data Source section, click Crawl selected external data source.
15. Select the NorthwindModel check box, and then click OK.
16. On the Manage Content Sources page, click the Northwind drop-down arrow, and then click Start
Full Crawl.

Wait for the crawl status to return to Idle, which could take several minutes.
18. When the crawl has completed, on the Quick Launch menu, under Diagnostics, click Crawl Log.
19. You should see the Northwind content source has indexed several items, but several have warnings.
These warnings are expected.
20. Open a new browser tab. In the Address bar, type http://search.contoso.com, and then press Enter.
21. On the Search page, in the text box, type Chef, and then press Enter. You should get back two items.
Results: A successfully deployed .NET Connectivity model.

L11-1
Module 11: Working with Business Data

Lab: Working with Business Data in Apps for
SharePoint
Exercise 1: Reading Business Data in Client-Side Code
1. Start the 20489A-LON-SP-11 virtual machine.
4. In File Explorer, browse to E:\Labfiles\Starter\ContosoODataService, and then double-click

ContosoODataService.sln.
6. In Visual Studio, in Solution Explorer, expand ContosoODataWebService, and then double-click

ContosoODataWebService.svc.
7. Review the InitializeService method. Notice that this method exposes the DimProducts,
DimProductCategories, and DimProductSubcategories entities. These map to the DimProduct,
DimProductCategory, and DimProductSubcategory database tables.
8. On the DEBUG menu, click Start Without Debugging. Leave the service running, because it is
required in the following tasks.

1. On the Taskbar, right-click Visual Studio, and then click Visual Studio 2012.
2. On the Start page, click New Project.
3. In the New Project dialog box, under Templates, expand Visual C#, expand Office/SharePoint, and
then click Apps.
4. In the templates list, click App for SharePoint 2013.
5. In the Name box, type AssetApp.
debugging your app, type http://dev.contoso.com/.
click Finish.
9. In Solution Explorer, right-click the AssetApp project, point to Add, and then click Content Types
for an External Data Source.
10. In the SharePoint Customization Wizard, in the What OData service URL do you want to use to
create the external data source box, type
http://localhost:12345/ContosoODataWebService.svc/.
11. In the What do you want to name your new data source box, type ContosoODataSource, and
then click Next.
12. On the Select the Data Entities page, select the DimProducts, and DimProductSubcategories
check boxes.
13. Confirm that the Create list instances for the selected data entities (except Service Operations)
check box is selected, and then click Finish.
 Task 3: Retrieve Asset Information by Using JSON

1. In Solution Explorer, expand Pages, and then double click Default.aspx.
2. Locate the div element near the bottom of the page. Delete this div element and all its contents.
3. In place of the element you just deleted, type the following:
<input id="cmdGetProducts" type="button" value="Get Products" />
4. On a new line immediately below the code you just added, type the following:
<div id="displayDiv" />
5. In Solution Explorer, expand Scripts, and then double click App.js.
6. Delete the entire contents of the App.js file.
8. In the Insert File dialog box, in the file type list, click All Files (*.*).
9. Browse to E:\Labfiles\Starter, click App01.txt, and then click Open.
10. Review the code you just added. The onGetProducts function retrieves data from the DimProducts
external list, which you configured in the previous task. The returned data is stored in a variable
named odataResult.
11. Click anywhere on the line that shows the following code, and then press F9 to add a breakpoint:
var oDataResult = data.d.results;
13. When the app has finished loading, in Internet Explorer, click Get Products.
14. When the debugger reaches the breakpoint, in Visual Studio, press F10.
15. Hover over the text odataResult, and then on the context menu, expand odataResult.
16. Verify that the odataResult variable contains multiple sets of data, and then on the DEBUG menu,
click Stop Debugging.
17. Press Ctrl+Shift+F9 to delete all breakpoints.
 Task 4: Display Asset Information in a Table

1. In Solution Explorer, double-click App.js.
2. Locate the onReturnData function, and delete all the code within the function (delete everything
within the curly brackets).
4. In the Insert File dialog box, in the file type list, click All Files (*.*).
5. Browse to E:\Labfiles\Starter, click App02.txt, and then click Open.

L11-3
6. Review the code you just added. The onGetProducts function renders the data from the external list
as a table.
8. When the page loads, click Get Products. Verify that the app displays a table containing product
data.
Results: After this exercise, you should have retrieved a list of products that are older than three years.
Exercise 2: Presenting Business Data in an App for SharePoint

 Task 1: Filter Data by Class
1. In Solution Explorer, double-click Default.aspx.
2. Locate the input element (near the bottom of the page).
3. On a new line immediately above the input element, add the following code:
<select id="lstClass">
<option value="'Economy'">Economy</option>
<option value="'Regular'">Regular</option>
<option value="'Deluxe'">Deluxe</option>
</select>
5. Add the following code to the beginning of the onGetProducts function:
var selectedClass = $("#lstClass").val();
var requestUri = _spPageContextInfo.webAbsoluteUrl +

"/_api/lists/getbytitle('DimProducts')/items"
7. Edit the line of code you just located to resemble the following:
var requestUri = _spPageContextInfo.webAbsoluteUrl +

"/_api/lists/getbytitle('DimProducts')/items?$filter=ClassName eq " + selectedClass;
8. Click Save All.

1. On the BUILD menu, click Rebuild Solution.
2. On the BUILD menu, click Deploy Solution.

4. When the page has finished loading, click Get Products.
5. Notice that the page only displays items with a Class value of Economy.
6. In the drop-down list, click Regular, and then click Get Products.
7. Notice that the page displays only items with a Class value of Regular.
8. In the drop-down list, click Deluxe, and then click Get Products.
9. Notice that the page displays only items with a Class value of Deluxe.
Results: After this exercise, you should have filtered the data retrieved from the OData by class name.
L12-1
Module 12: Managing and Accessing User Profile Data

Lab A: Accessing User Profile Data
Exercise 1: Add People Search Functionality to an App
 Task 1: Review the starter solution
2. In Visual Studio, on the FILE menu, point to Open, and then click Project/Solution.
3. In the Open Project dialog box, browse to E:\Labfiles\Starter\CUPA, click

ContosoUserProfileApp.sln, and then click Open.
4. In Solution Explorer, expand Pages, and then double-click Default.aspx.

5. In the Default.aspx file, review the markup. Notice that the file contains a div element with the id
search, and a div element with the id results.
 Task 2: Add Controls to Enable Users to Enter Search Criteria

1. In the Default.aspx file, locate the following code:
<div id="search">
<p>
<label>Account Name</label><input type="text" id="accountName" />
</p>
<p>
<label>Name</label><input type="text" id="name" />
</p>
<p>
<label> Department </label><input type="text" id="department" />
</p>
<p>
<button type="button" id="submitSearch">Search</button>
</p>
<div id="results">
<p>
<a href="#" onclick="Contoso.UserProfileApp.showSearch()">New Search</a>
</p>
<div id="users">
</div>
5. In Solution Explorer, expand Content, and then double-click App.css.
6. In the App.css file, review the markup. Notice that the markup defines the layout for the elements
you have added in this task.
 Task 3: Add code to search for users.

1. Switch to the Default.aspx file.
<script type="text/javascript" src="/_layouts/15/sp.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.search.js"></script>
var clientContext = SP.ClientContent.get_current();
6. Place the cursor on a new line after the line you located in the previous step.
8. In the Insert File dialog box, browse to E:\Labfiles\Snippets, in the file type list, click All Files (*.*),
click searchUsersFunction.txt, and then click Open.
function showSearch() {
$("#search").show();
$("#results").hide();
}
return {
searchUsers: searchUsers,
$(document).ready(function() {
$('#submitSearch').click(Contoso.UserProfileApp.searchUsers);

2. In Internet Explorer, on the Do you trust ContosoUserProfileApp page, click Trust It.
3. On the User Profile Search page, in the Account Name box, type Administrator, and then click
Search.
4. Verify that a single user is returned with the display name Administrator.
5. Click New Search.

6. In the Name box, type Smith, and then click Search.
7. Verify that two results are returned.

L12-3
10. Verify that SharePoint returns approximately 50 users.
12. In the Name box, type Smith.
14. Verify that a single user is returned with the display name Denise Smith.
Results: After completing this exercise, you should have added search functionality to an app.
Exercise 2: Display User Properties in the App

 Task 1: Add code to retrieve user profile properties
1. In Visual Studio, switch to the Default.aspx file.
<script type="text/javascript" src="/_layouts/15/sp.search.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.userprofiles.js"></script>
<div id="users">
</div>
<div id="profile">
</div>
6. Switch to the App.js file.
alert("Error performing search.");

});
}
8. Place the cursor on a new line after the line you located in the previous step.
10. In the Insert File dialog box, browse to E:\Labfiles\Snippets, in the file type list, click All Files (*.*),
click displayProfileFunction.txt, and then click Open.
searchUsers: searchUsers,
displayProfile: displayProfile,
$("#users").html("");
$("#profile").html("");
$("#users").append("<div>" + this.PreferredName + "</div>");
16. Replace the located code, with the following code:
$("#users").append("<div>" +
"<a href='#'
onclick='Contoso.UserProfileApp.displayProfile(this)' data-username='" +
this.AccountName + "'>" + this.PreferredName + "</a></div>");

2. If SharePoint displays a Do you trust ContosoUserProfileApp? page, on the Do you trust

ContosoUserProfileApp? page, click Trust It.
3. On the User Profile Search page, in the Name box, type Smith, and then click Search.
4. Click Denise Smith.
5. Verify that the app displays the profile information for Denise Smith.
Results: After completing this exercise, you should have modified an app to retrieve a user profile.
L12-5
Lab B: Managing User Profile Properties

Exercise 1: Add Code to Display User Profile Properties
 Task 1: Grant the Domain Admins Account Administrative Permissions on the User
Profile Service Application
2. In Internet Explorer, under Application Management, click Manage service applications.
3. On the Manage Service Applications page, click the User Profile Service Application row (do not
click the Contoso User Profiles text).
4. On the ribbon, click Administrators.
5. In the Administrators for Contoso User Profiles dialog box, in the text box, type Domain Admins,
and then click Add.
6. Under Permissions for CONTOSO\domain admins, select the Manage Profiles check box, and
then click OK.
 Task 2: Add Code to Display User Profile Properties

3. In the Open Project dialog box, browse to E:\Labfiles\Starter\CMPWP, click
ContosoManagePropertiesWebPart.sln, and then click Open.
4. In Solution Explorer, expand ContosoManagePropertiesWebPart, and then double-click

ContosoManagePropertiesWebPart.ascx.
5. Review the ContosoManagePropertiesWebPart.ascx file. Notice that the file defines a text box, two
buttons and a table.
6. In Solution Explorer, right-click References, and then click Add Reference.
7. In the Reference Manager - ContosoManagerPropertiesWebPart dialog box, in the Search

Assemblies box, type Microsoft.Office.Server.
8. Select the Microsoft.Office.Server, and Microsoft.Office.Server.UserProfiles check boxes, and
then click OK.
9. In Solution Explorer, expand ContosoManagePropertiesWebPart.ascx, and then double-click

ContosoManagePropertiesWebPart.ascx.cs.
10. In the ContosoManagePropertiesWebPart.ascx.cs file, add the following using statements:
using Microsoft.Office.Server.UserProfiles;
protected override void OnInit(EventArgs e)

{
base.OnInit(e);
InitializeControl();
}
12. Place the cursor on a new line after the code you just located.
14. In the Insert File dialog box, browse to E:\Labfiles\Snippets, in the file types list, click All Files (*.*),
click LoadPropertiesMethod.txt, and then click Open.
protected override void OnInit(EventArgs e)

{
base.OnInit(e);
InitializeControl();
LoadProperties();
propertiesTable.Rows.Add(row);
}
}
private void privacyOptions_SelectedIndexChanged(object sender, EventArgs e)

{
}
private void addProperty_Click(object sender, EventArgs e)
{
}
private void deleteButton_Click(object sender, EventArgs e)
{
}

2. In the Debugging Not Enabled dialog box, click OK.
3. In Internet Explorer, on the Contoso Development Site page, on the PAGE menu, click Edit.
4. In the edit view, click in the box on the line above the Get started with Apps for Office and
SharePoint text.
5. On the INSERT menu, click Web Part.
6. In the Categories list, click Custom, in the Parts list, click ContosoManagePropertiesWebPart, and
then click Add.


L12-7
8. Verify that the ContosoManagePropertiesWebPart displays a list of properties and a corresponding

privacy setting and Delete button for each property.
Results: After completing this exercise, you should have added code to display user profile properties on
a web part.
Exercise 2: Add Code to Manage User Profile Properties

 Task 1: Add Code to Create a New User Profile Property
private void addProperty_Click(object sender, EventArgs e)

{
click addPropertyMethod.txt, and then click Open.
 Task 2: Add Code to Delete a User Profile Property

private void deleteButton_Click(object sender, EventArgs e)

{
click deletePropertyMethod.txt, and then click Open.
 Task 3: Add Code to Update a User Profile Property

private void privacyOptions_SelectedIndexChanged(object sender, EventArgs e)

{
click privacyOptions_SelectedIndexChangedMethod.txt, and then click Open


2. In Internet Explorer, on the Contoso Development Site page, in the text box, type New Property,
and then click Add Property. After you click Add Property, the page may take some time to update.
Wait for the page to update before you continue. Do not click Add Property twice, or the code may
throw an exception.
3. In the NewProperty row, in the Privacy list, click Private, and then click Save Changes. When the
page reloads, verify that the default privacy for the NewProperty is now Private.
4. In the NewProperty row, click Delete. When the page reloads, verify that the NewProperty row has
been removed.
Results: After completing this exercise, you should have updated a web part to include functionality to
manage user profile properties.
L13-1
Module 13: Customizing the Social Workload

Lab: Creating a Social App Part
Exercise 1: Displaying a Project Site Newsfeed
 Task 1: Set Permission Requirements
3. On the Start screen, click Visual Studio 2012.
5. In the Open Project dialog box, browse to E:\Labfiles\Starter\ContosoFeedApp, click

ContosoFeedApp.sln, and then click Open.
6. In Solution Explorer, expand ContosoFeedApp, and then double-click AppManifest.xml.
7. In the properties window, click on the Permissions tab.
8. Click the empty Scope field, and then in the list, click Tenant.
Note: The Tenant permission simplifies the debugging process. In a production app you should use
the most restrictive permissions requirements that are necessary for your app.
9. Click the empty Permission field next to the Scope you have just set, and then from the list, click
Write.
10. Click in the empty Scope field, and then in the list, click User Profiles (Social).
11. Click in the empty Permission field next to the Scope you have just set, and then in the list, click
Read.
12. Click Save, and then close the properties window.
 Task 2: Add Code to Load the Project Site Newsfeed

2. In the code editor, locate the comment // TODO: Add code to load the site's newsfeed.
3. On a new line after the comment you have just located, type the following code:
var siteFeed;
$.ajax({
url: Utilities.appWebUrl + "/_api/social.feed/actor(item=@v)/feed?@v='" +
Utilities.hostWebUrl + "/newsfeed.aspx'",
headers: {
},
siteFeed = getSiteFeedSuccess(data);
},
error: function (xhr, ajaxOptions, thrownError) {
alert("Error: " + xhr.status + " " + thrownError + "\nResponseText: " +
xhr.responseText);
},
});
return siteFeed;
4. Locate the comment // Add code to process the newsfeed after the feed has been retrieved.
feedPosts = data.d.SocialFeed.Threads.results.reverse();
Contoso.NewsfeedApp.feedPosts = feedPosts;
Display.updateDisplay();
6. Locate the comment // TODO: Add code to update the newsfeed when the app launches.
Contoso.NewsfeedApp.updateFeed();

2. In Internet Explorer, on the Do you trust ContosoFeedApp page, click Trust It.
3. On the ribbon, on the PAGE tab, click Edit.

4. On the ribbon, on the INSERT tab, click App Part.
5. In the Parts list, click ContosoFeedAppPart Title, and then click Add.
7. Verify that a newsfeed is displayed and includes the message Welcome to the project site for
project 2822.
Results: After completing this exercise, you should have modified an app part to display a newsfeed from
a project site.
Exercise 2: Posting a Message to a Newsfeed

 Task 1: Add Controls to the User Interface
1. In Visual Studio, in Solution Explorer, expand Pages, and then double-click
ContosoFeedAppPart.aspx.
2. Locate the comment .
3. On a new line after the comment you have just located, type the following markup:
<textarea id="StatusTextArea" cols="50" rows="2"></textarea>

<button id="PostStatus" type="button">Post</button>
5. In the code editor, locate the following comment // TODO: Add code to add a click event handler
to the post button.
$('#PostStatus').click(Contoso.NewsfeedApp.post);
L13-3
 Task 2: Add Code to Submit a Post

1. In the App.js file, locate the following comment // TODO: Review the getProjectCode function.
Review the getProjectCode function. This function sets the Utilities.projectSiteCode variable by
retrieving the project code that is stored in the site property bag. This function is self-invoking, so
runs as soon as the app starts.
2. Locate the following comment // TODO: Add code to send the new post to SharePoint.
var userContent = $("#StatusTextArea").val();

userContent += " #" + Utilities.projectSiteCode;
var contentArray = userContent.split(" ")
var tags = new Array();
var tagCount = 0;
$.each(contentArray, function (index) {
if (this.indexOf("#") == 0) {
var tag = new SP.Social.SocialDataItem();
tag.ItemType = 3;
tag.Text = this;
tags.push(tag);
contentArray[index] = "{" + tagCount + "}";
tagCount++;
}
});
userContent = "";
$.each(contentArray, function () {
userContent += " " + this;
});
4. On a new line after the code you have just typed, type the following code:
$.ajax({
url: Utilities.appWebUrl + "/_api/social.feed/actor(item=@v)/feed/post?@v='" +
Utilities.hostWebUrl + "/newsfeed.aspx'",
type: 'POST',
'__metadata': {
'type': 'SP.Social.SocialRestPostCreationData'
},
'ID': null,
'creationData': {
'__metadata': {
},
'ContentItems': {
'results': tags
},
'ContentText': userContent,
}
}
}),
headers: {
'X-RequestDigest': Utilities.formDigest
},
success: sendPostSuccess,
error: function () {
xhr.responseText);
}
});
$("#StatusTextArea").val("");
5. Locate the following comment // TODO: Add code to update the feed after a post is successfully
added.
Feed.updateFeed();

1. On the Debug menu, click Start Without Debugging.
2. In Internet Explorer, in the ContosoFeedAppPart Title text box, type Sent from the app, and then
click Post.
3. Verify that the feed is updated with a post containing Sent from the app #P2822.
5. Verify that the first post in the feed contains the text Sent from the app #P2822.
Results: After completing this exercise, you should have added controls and code to an app part to
support posting a message to a newsfeed.
Exercise 3: Using Search to Retrieve Newsfeed Posts

 Task 1: Modify the getSiteFeedSuccess Function to Use Search
1. In Visual Studio, in Solution Explorer, double-click AppManifest.xml.
2. In the properties window, on the Permissions tab, click the empty Scope row, and then in the list,
click Search.
3. Click the empty Permission row, in the list, click QueryAsUserIgnoreAppPrincipal, and then click
Save.
5. In the code editor, locate the following lines of code:
// Add code to process the newsfeed after the feed has been retrieved.
feedPosts = data.d.SocialFeed.Threads.results.reverse();
6. On a new line after the lines of code you have just located, type the following code:
var queryString = "(ContentTypeId:0x01FD4FB0210AB50249908EAA47E6BD3CFE8B* OR

ContentTypeId:0x01FD59A0DF25F1E14AB882D2C87D4874CF84* OR ContentTypeId:0x012002* OR
ContentTypeId:0x0107* OR WebTemplate=COMMUNITY)owstaxIdMetadataAllTagsInfo:" +
Utilities.projectSiteCode;
var keywordQuery = new
Microsoft.SharePoint.Client.Search.Query.KeywordQuery(Utilities.clientContext);
keywordQuery.set_queryText(queryString);
var sortList = keywordQuery.get_sortList();
L13-5
sortList.add("LastModifiedTime",
Microsoft.SharePoint.Client.Search.Query.SortDirection.Ascending);
keywordQuery.set_enableSorting(true);
var searchExecutor = new
Microsoft.SharePoint.Client.Search.Query.SearchExecutor(Utilities.clientContext);
var results = searchExecutor.executeQuery(keywordQuery);
Utilities.clientContext.executeQueryAsync(function () {
var resultRows = results.m_value.ResultTables[0].ResultRows;
Contoso.NewsfeedApp.searchResults = resultRows;
Display.updateDisplay();
8. On a new line after the line of code you have just located, type the following code:
},
function () {
alert("Search failed.");
});
 Task 2: Add Code to Retrieve Actor Information

1. Locate the follow comment // TODO: Review the updateDisplay function.
Review the code in the updateDisplay function. In the updateDisplay function, data from both the
newsfeed and search results are merged. Because the results from the search service are not in the
same format as the posts from the current site, the updateDisplay function uses a utility function
named getActorInfo to retrieve missing information about the post author.
2. Locate the following comment // TODO: Review the addToFeed function.

Review the code in the addToFeed function. In this function, individual posts are parsed and HTML
markup is added to a variable for display on the page.
3. Locate the following comment // TODO: Add code to retrieve the actor for the specified account.
var actorInfo = "";

$.ajax({
url: appWebUrl + "/_api/social.feed/actor(item='" + accountName + "')",
headers: {
},
actorInfo = data.d.FollowableItemActor;
},
error: function (xhr, ajaxOptions, thrownError) {
xhr.responseText);
},
async: false
})
return actorInfo;

2. In Internet Explorer, on the Do you trust ContosoFeedApp page, click Trust It.
3. On the ribbon, on the PAGE tab, click Edit.

4. On the ribbon, on the INSERT tab, click App Part.
5. In the Parts list, click ContosoFeedAppPart Title, and then click Add.
7. Verify that the feed on the page now includes a message from Pat Coleman asking for help on a case
study she is producing. This post is from Pat’s My Site newsfeed.
Results: After completing this exercise, you should have modified the app part to display posts retrieved
by using the search service.
L14-1
Module 14: Monitoring and Troubleshooting Custom

SharePoint Solutions
Lab: Enabling ASP.NET Tracing
Exercise 1: Adding a Diagnostics Page to a SharePoint App
 Task 1: Add a Diagnostics Action to the Home Controller
4. In File Explorer, browse to E:\Labfiles\Starter\MileageRecorder, and then double-click

MileageRecorder.sln.
5. When the how do you want to open this type of file (.sln)? dialog appears click Visual Studio
2012.
6. In Solution Explorer, in the MileageRecorderRemoteWeb project, expand the Controllers project,
and then double-click HomeController.cs.
7. In the HomeController.cs code file, locate the following lines of code:
public ActionResult Index()

{
return View();
}
8. Immediately after the located code, insert the following lines of code:
public ActionResult Diagnostics()

{
9. Place the cursor within the Diagnostics method you just created, and then type the following code:
return View();
 Task 2: Add a Diagnostics View

1. In the HomeController.cs code file, right-click the following line of code, and then click Add View:
2. In the Add View dialog box, click Add.
 Task 3: Link to the Diagnostics View

1. In Solution Explorer, expand the Scripts folder, and then double-click App.js.
2. In the App.js code file, locate the following line of code:

"appTitle": "Contoso Ledgers App"
"appTitle": "Contoso Mileage Recorder",
4. Press Enter.
"settingsLinks": [
{
}
]
6. Place the cursor within the settingsLinks property object you just created, and then type the
following code:
"linkUrl": "../Home/Diagnostics?" + document.URL.split("?")[1],
7. Press Enter.
"displayName": "Diagnostics"
 Task 4: Test the Diagnostic View

2. In the Security Alert dialog box, click Yes.
3. In the Security Warning dialog box, click Yes.
4. On the Do you trust Mileage Recorder? page, click Trust It.
5. On the Contoso Mileage Recorder page, click the Settings icon, and then click Diagnostics.
Results: A SharePoint auto-hosted app with a new Diagnostics page.

L14-3
Exercise 2: Configuring ASP.NET Tracing

 Task 1: Edit Web.config
1. In Visual Studio, in Solution Explorer, under the MileageRecorderRemoteWeb project, double-click
Web.config.
Note: Be careful to double-click the Web.config file in the root of the project, not the
Web.config file in the Views folder.
2. In the Web.config file, locate the following line of code:
</system.web>
3. Immediately before the located code, insert the following lines of code:
<trace enabled="false"
localOnly="false"
mostRecent="true"
pageOutput="false"
requestLimit="100"
traceMode="SortByTime"
writeToDiagnosticsTrace="true" />
5. On the FILE menu, click Close.
 Task 2: Display Tracing Status

1. In Solution Explorer, in the Controllers folder, double-click HomeController.cs.
2. In the HomeController.cs code file, locate the following lines of code:

{
3. Immediately after the located code, insert the following line of code:
Configuration currentConfig = WebConfigurationManager.OpenWebConfiguration("~");
4. Press Enter.
TraceSection traceSection =
(TraceSection)currentConfig.GetSection("system.web/trace");
6. Press Enter.
ViewBag.TracingStatus = traceSection.Enabled;
8. In Solution Explorer, expand Views, expand Home, and then double-click Diagnostics.cshtml.
9. At the bottom of the view, insert the following lines of code:
@if (ViewBag.TracingStatus)
{
}
else
{
}
10. Place the cursor within the if code block you just created, and then type the following code:
<p>Tracing Status: Enabled</p>
11. Place the cursor within the else code block you just created, and then type the following code:
<p>Tracing Status: Disabled</p>
 Task 3: Enable Users to Toggle Tracing

1. In Solution Explorer, in the Controllers folder, double-click HomeController.cs.
2. Place the cursor after the end of the Diagnostics action but within the HomeController class, and
then type the following code:
public ActionResult ToggleTracing(bool switchOn)

{
}
3. Place the cursor within the ToggleTracing action you just created, and then type the following code:
Configuration currentConfig = WebConfigurationManager.OpenWebConfiguration("~");
4. Press Enter.
TraceSection traceSection =
(TraceSection)currentConfig.GetSection("system.web/trace");
6. Press Enter.
traceSection.Enabled = switchOn;
8. Press Enter.
currentConfig.Save();
10. Press Enter.
ViewBag.TracingStatus = switchOn;
12. Press Enter.

L14-5
return View("Diagnostics");
 Task 4: Build the Diagnostics User Interface

1. In Solution Explorer, in the Home folder, double-click Diagnostics.cshtml.
2. In the Diagnostics.cshtml view, locate the following line of code:
<p>Tracing Status: Enabled</p>
<p>
@Html.ActionLink("Switch Off Tracing", "ToggleTracing", new { controller = "Home",
switchOn = false, SPHostUrl = Request.QueryString["SPHostUrl"], SPAppWebUrl =
Request.QueryString["SPAppWebUrl"] });
</p>
4. Press Enter.
<p><a href="~/trace.axd">View Trace Logs</a></p>
<p>Tracing Status: Disabled</p>
<p>
@Html.ActionLink("Switch On Tracing", "ToggleTracing", new { controller = "Home",
switchOn = true, SPHostUrl = Request.QueryString["SPHostUrl"], SPAppWebUrl =
Request.QueryString["SPAppWebUrl"] });
</p>
Results: A SharePoint auto-hosted app with tracing facilities.
Exercise 3: Using Trace Logs

 Task 1: Enable Tracing
1. In Visual Studio, on the DEBUG menu, click Start Debugging.
2. If SharePoint displays the Do you trust Mileage Recorder? page, on the Do you trust the Mileage
Recorder? page, click Trust It.
4. Click Switch On Tracing.

 Task 2: Make Test Requests

1. In the top-left of the Contoso Mileage Recorder Diagnostics page, click Contoso Mileage Recorder.
2. On the Contoso Mileage Recorder page, click Make a Claim.
3. In the Destination box, type New York.
4. In the Reason for trip box, type Business Meeting.
5. In the Miles box, type 100.
6. In the Engine size box, type 1600, and then click Create.
 Task 3: View Trace Logs

2. Click View Trace Logs.
3. On the Application Trace page, locate the tracing entry that records a GET request for the
Home/Diagnostics page, and then click View Details.
4. On the Request Details page, locate the Querystring Collection section.
5. Record the value for the SPAppWebUrl query string parameter.
6. In the address bar, click the Back button.
7. Locate the tracing entry that records a POST request for the MileageClaim/Create address, and then
click View Details.
8. On the Request Details page, locate the Form Collection section.
9. Record the value for the ReasonForTrip parameter.

12. On the Diagnostics page, click Switch Off Tracing.
Results: A SharePoint auto-hosted app in which users can enable tracing and view tracing logs to supply
information about bugs and other issues.

20489B ENU TrainerHandbook

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

20489B ENU TrainerHandbook

Uploaded by

Copyright:

Available Formats

MCT USE ONLY.

STUDENT USE PROHIBITED

Microsoft and the trademarks listed at

Product Number: 20489B

a. If you are a Microsoft IT Academy Program Member:

b. If you are a Microsoft Learning Competency Member:

d. If you are an End User:

e. If you are a Trainer.

3. LICENSED CONTENT BASED ON PRE-RELEASE TECHNOLOGY. If the Licensed Content’s subject

11. APPLICABLE LAW.

This limitation applies to

LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES

Revised September 2012

Paul Barnes – Content Developer

Chris Beckett – Content Developer

Chris Givens – Content Developer

Scot Hillier – Technical Reviewer

Jason Lee – Content Developer

Alistair Matthews – Content Developer

Telmo Sampaio – Content Developer

Mike Sumsion – Content Developer

Module 2: Developing Managed Metadata Solutions

Module 3: Interacting with the Search Service

Module 4: Customizing the Search Experience

Module 5: Implementing Enterprise Content Management

Module 6: Developing a Publishing Site for Web Content

Module 7: Structuring and Publishing Websites for All Users

Module 8: Developing Optimized Internet Sites

Module 9: Working with Business Connectivity Services

Module 10: Creating Advanced Business Data Connectivity Models

Module 11: Working with Business Data

Module 12: Managing and Accessing User Profile Data

Module 13: Customizing the Social Workload

Lab: Creating a Social App Part 13-23

Module 14: Monitoring and Troubleshooting Custom SharePoint Solutions

Lab Answer Keys

About This Course

 Selecting an appropriate approach and building customizations in SharePoint.

 Identifying SharePoint data and content structures for customizations.

 Performing diagnostics and debugging.

 Identifying and mitigating performance issues of customizations.

 Understanding authentication and authorization.

 Experience with Windows PowerShell.

 Broad familiarity with SharePoint capabilities.

 Familiarity with Online Services such as Azure and SharePoint Online.

 Completion of course 20488 or equivalent technical knowledge.

 A basic working knowledge of SharePoint solution development, either in SharePoint 2013 or in

 A working knowledge of Visual C# and the .NET Framework 4.5.

 A basic understanding of ASP.NET and server-side web development technologies, including

 A basic understanding of AJAX and asynchronous programming techniques.

 Familiarity with approaches to authentication and authorization, including claims-based

 Develop robust and efficient apps for SharePoint.

 Configure records management and e-discovery solutions.

 Develop components for publishing sites.

 Develop websites for multiple languages and multiple devices.

 Optimize internet sites for search and performance.

 Create advanced BDS models and custom connectors.

 Interact with social functionality from custom SharePoint solutions.

 Monitor and troubleshoot custom SharePoint solutions.

Module 2, "Developing Managed Metadata Solutions"

Module 3, "Interacting with the Search Service"

Module 4, "Customizing the Search Experience"

Module 5, "Implementing Enterprise Content Management"