Sharepoint Online Custom Solution Resources Applies To: Office 365 Dedicated – Legacy Release

SharePoint Online Custom Solution Resources Applies to: Office 365 Dedicated – Legacy Release

Topic Last Modified: 2014-04-07 This section describes resources available to customers and third party providers building custom solutions for SharePoint Online Dedicated.

Custom Solutions Resources for SharePoint Online Dedicated

The resources available to developers of SharePoint Online custom solutions include:  Custom Solution Policies and Process (FTC) This article describes the policies and process that govern how Microsoft and its subscribers to SharePoint Online for enterprises dedicated plans validate and deploy custom solutions to the SharePoint Online environment.  SharePoint Online Custom Solution Developer's Guide (Dedicated Plans) This article provides SharePoint Online Dedicated plan customers with guidelines and best practices to help you develop custom solutions that you can deploy to the SharePoint Online environment.  Submitting Custom Solutions to SharePoint Online Using MSOCAF This article describes how to use Microsoft SharePoint Online Code Analysis Framework (MSOCAF), which is the tool you use to validate and submit SharePoint Online custom solutions.

Custom Solution Policies and Process (FTC) Topic Last Modified: 2014-04-11 This article describes the policies and process that govern how Microsoft and its subscribers to SharePoint Online Dedicated validate and deploy custom solutions to the SharePoint Online environment. These custom solutions include solutions and products that are developed by third parties and code developed in-house by customers. Custom solutions can be deployed to any web application in the SharePoint Online Dedicated environment (Portal, Team, Partner, or Personal Sites). Topics include:  Custom Solution Policies and Process Introduction  Custom Solution Process  Custom Solution Policies  Custom Policies and Process Appendix

Custom Solution Policies and Process Introduction Topic Last Modified: 2014-04-16

Introduction

This article describes the policies and process for creating, validating, and deploying custom solutions for SharePoint Online using the full trust code method. This method helps ensure a successful deployment of your custom solutions. Custom solutions can be deployed to any web application in the SharePoint Online Dedicated environment (Portal, Team, Partner, or Personal Sites). Your custom solutions can include solutions and products that are developed by third parties, as well as code that you develop in-house. The goal of these guidelines is to ensure that a custom solutions deployed to the SharePoint Online environment can be operated, managed, secured, and scaled following established best practices. To meet that goal, Microsoft:  Checks whether an existing custom solution, or an out-of-the-box solution, can accomplish the same goals as the proposed custom solution.  Reviews the high-level design of custom solutions.  Provides feedback to ensure your custom solutions can be hosted by SharePoint Online.  Evaluates the custom solution deployment package and the final custom solution code to ensure they can be deployed to and hosted on the SharePoint Online environment. The review incorporates manual test cases and follows best practices established by Microsoft.  Deploys custom solutions in Microsoft test environments for a complete deployment review and release verification. These guidelines are only for fully trusted code that is deployed or executed by Microsoft on Microsoft SharePoint 2010 or Office SharePoint Server 2007 servers. Typically, this includes code based on

Microsoft .NET Framework and dependent files, but can also include Windows PowerShell scripts or batch files. These guidelines do not apply to other methods of customizing a SharePoint Online environment, such as:  End-user solutions. A customization that is performed through a web-based mechanism, such as applying style sheets, out-of-the-box Web Parts, or page templates.  Authored site customization. A customization that is performed by web designers using HTML editors, such as customization of master pages or page layouts. This also includes declarative solutions using SharePoint Designer and SharePoint site administrative pages in a browser, such as data access with Business Connectivity Services or connecting list and data view Web Parts.  Sandboxed solutions (partially trusted code). A customization created by developers. These solutions typically contain .NET Framework–based code and dependent files deployed to SharePoint site collections by your site collection administrators. However, we do recommend analyzing the code of a sandboxed solution by using the Microsoft SharePoint Online Code Analysis Framework tool (MSOCAF). For an introduction to the MSOCAF tool, see About MSOCAF. To learn more about using sandboxed solutions, see Appendix A: SharePoint Online Policies for Sandboxed Solutions.

Security Note: Please keep the following in mind when using these guidelines:  The policies and process described here don’t apply to standard configurations. They apply only to custom solutions.  Don’t include standard Configuration Request (CR) changes when you submit your copy of the deployment guide (MSODeploymentGuide). For standard configurations, contact your Microsoft service delivery manager (SDM) to submit a CR for the standard configuration change. Use the CR templates available on the Service Administration portal. Benefits When you develop custom solutions with Microsoft, you gain:  A structured process. Microsoft uses a structured review process to help with custom solution performance, scalability, availability, and upgrade.  Experience in deploying custom solutions. Microsoft has extensive experience with deploying custom solutions, including custom-written, off-the-shelf, and hybrid solutions that rely on custom code and third-party products.

 Capacity planning experience. Microsoft has experience with evaluating how a custom solution is managed, monitored, and instrumented, and whether it has the ability to scale, Microsoft can also suggest an infrastructure design to meet your needs. What You Should Know You should have experience with:  Internet Information Services (IIS).  Life-cycle-based development and testing of .NET Framework-based code. For more developer resources about the development process and best practices, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). Custom Solution Reviews Microsoft reviews the proposed design of your custom solutions at an early stage and the packaged solution after it has been developed. Microsoft waits until after you validate the service before reviewing any of your custom solutions. If you choose to develop and submit farm-level custom solutions for deployment by Microsoft, you can do so after purchasing custom solution credits. You must allow the necessary time for these reviews when you schedule custom solution development and deployment, as described in Custom Solution Process. You will receive a change window schedule from your service delivery manager (SDM) to help you calculate the work-back dates for:  Developing your custom solution.  Submitting a deployment package.  The test and review process.

Custom Solution Parameters When Microsoft acknowledges receipt of a custom solution that you have submitted for deployment, you‘re charged for one or more custom solution credits. The number of custom solution credits you’re charged is based on the amount of code and the number of solution packages as detailed in Custom Solution Scoping Policy.

Note: Credits are purchased as a Deployment and Upgrade Pack. For more information, contact the relevant sales team. However, you aren’t charged a custom solution credit when an update to a custom solution falls within the scope of the original SharePoint Online High Level Design (HLD) document. For example, you aren’t charged when you update a custom solution to work with a newer version of SharePoint, or if you discover a bug that requires a code change but not an HLD change. There is also no charge for reviewing third-party solutions for use in the SharePoint Online environment or for deploying those third-party solutions. About MSOCAF Microsoft SharePoint Online Code Analysis Framework (MSOCAF) is the tool you use to validate and submit SharePoint Online custom solutions. MSOCAF includes a set of executable rules to help you analyze custom solutions you plan to deploy to SharePoint Online prior to submitting those solutions for deployment. This means you can identify and address any code issues before submission.

Important: You must use MSOCAF and submit a deployment manifest to complete the custom solution deployment process.

Important: MSOCAF performs only code validation and deployment testing. Functional testing and stress, or load, testing must be done separately by your development team. Because the SharePoint Online service doesn’t include a hosted development or testing environment, all development and testing must take place in environments that are hosted by you. Testing should specifically take place in a farm environment rather than a standalone environment. For information on building these environments, refer to the SharePoint Online Customer Build Guide and the Performance Test Policy.

Note: Contact and confer with your SDM before using the Customer Build Guide.

The SharePoint Online service includes a pre-production environment (PPE) that you can use to validate the custom solution before you deploy it to the production environment. However, the PPE is not a substitute for a customer-hosted or partner-hosted test environment. For more information about the PPE, see Pre-Production Environment Validation. The SharePoint Online engineering team might continue to add rules and plug-ins according to the MSOCAF compliance policy, which is described in MSOCAF Compliance Policy. This enables Microsoft to automatically perform updates or add new rules and test cases according to the compliance policy without the need for you to reinstall the framework. MSOCAF must be used to validate all custom solutions developed for SharePoint Online by both you and independent software vendors (ISVs). Custom solutions you develop for SharePoint Online must use solution package (.wsp) files. To use MSOCAF with a custom solution, the deployment package also must be organized into a specific directory structure as described in SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). When you submit the deployment package, MSOCAF validates that the directory structure is correct and that all required components are included, and then packages all of the files into a single cabinet (.cab) file. MSOCAF calls a hosted web service to validate the user name and the CR number. If both elements are valid, MSOCAF uploads the .cab file. After the upload completes, you will receive a confirmation message by email.

Note: The .cab files you use for automated submission can’t be any larger than 250 megabytes (MB) each. If the .cab file size exceeds this amount, then you must submit the package manually to your SDM. For more information about downloading and using MSOCAF, see Submitting Custom Solutions to SharePoint Online Using MSOCAF. Potential Hardware and Service Impact

Custom solutions can significantly impact the SharePoint Online environment, especially when the code generates a high load, requires significant resources, or doesn't scale to the current environment. To address these issues, it might be necessary to:  Purchase additional hardware.  Upgrade existing hardware components.  Scale back custom solution deployment by deploying to fewer sites or pages.  Remove the custom solution entirely. During the custom solution review, the SharePoint Online engineering team determines whether there might be a need for additional hardware or upgraded components.

Note: In cases where hosting a custom solution requires the purchase of additional hardware, Microsoft reserves the right to charge for the required hardware and to delay deployment until the hardware has been procured and configured. Microsoft also reserves the right to reject the custom solution depending on the additional hardware needed to implement it.

Custom Solution Monitoring Microsoft monitors custom solutions that you deploy based on the defined monitoring rules that you provide, as described in System Monitoring Policy. Monitoring of custom solutions by Microsoft is effective only if you provide complete and usable troubleshooting guides and if your custom solutions implement the proper instrumentation to support monitoring. If a custom solution has an adverse impact on your environment, or if it affects the ability of Microsoft to meet your service-level agreement (SLA), Microsoft takes immediate action. This includes removing the custom solution to return the environment to a stable state, or optimizing it for current load and stress conditions. For more information about post-deployment issues, see Appendix C: Escalating Custom Solution Post-Deployment Issues. Use of Third-Party Components and Products You can use third-party components and products in your custom solutions. However, you must also use MSOCAF to validate any third-party components that are not already deployed to the SharePoint Online environment. Microsoft maintains a list of third-party solutions and products that have

previously been submitted and passed MSOCAF-based tests. For a full list of the MSOCAF-tested third- party solutions, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans).

Important: Testing of a third-party component is version-specific. If your custom solution uses a newer version of a third-party component, you must also test and submit the new version with MSOCAF.

Note: Some of these third-party solutions may also require changes to the hardware resources or support resources associated with a customer's deployment. Third-Party Solution Licensing You’re responsible for obtaining the necessary third-party licenses for deployment to all environments: the primary, secondary (failover), and PPE environments. You’re also responsible for determining any dependencies you need to activate a third-party solution in the SharePoint farm, and for securing product support from the third-party developer. Furthermore, you must provide proof of this licensing, often a key or certificate, as a part of the custom solution deployment package.

Note: Microsoft strongly recommends that you do not purchase a third-party custom solution until the design and architecture have first been reviewed by Microsoft, and the code has been tested using MSOCAF. Vendors often will not reimburse customers that have purchased a custom solution that is later rejected by Microsoft. Open Source Code Support Microsoft supports the use of open source code in custom solutions if you first take responsibility, in writing, for the ownership of the code. You must also ensure that such code has been tested for performance, scalability, stability, data integrity, and sustainability. You’re also responsible for end-to- end support of open source code, and the code must be tested using MSOCAF. If Microsoft encounters any issues when deploying custom solutions that use open source code to the production environment, Microsoft transfers those issues to you for further triage and root cause analysis.

Custom Solution Process Topic Last Modified: 2015-03-09

Custom Solution Process

If you want to introduce custom solutions that involve full trust code within the SharePoint Online production environment, or revise existing ones, you must follow a development and deployment process that has been established by Microsoft. This process is based on best practices developed by Microsoft through its work in hosting the SharePoint Online service. The process is also closely aligned with the Microsoft Solutions Framework (MSF) and the Microsoft Operations Framework. For more information about the MSF, download Microsoft Solutions Framework version 3 white papers. For more information about the Microsoft Operations Framework, see Microsoft Operations Framework 4.0. Development for the SharePoint Online environment is similar to any software development process. The process should follow an established methodology such as the MSF, as shown in the following illustration.

For a richer explanation of this model, see MSF Process Model Overview. Overview of the Custom Solution Process The following is an overview of the steps that are required as part of the development and deployment process for custom solutions, using a sample timeline and process. You must perform steps 1, 2, 4, and 5 of this process; steps 3 and 6 are performed by Microsoft, as shown in the following illustration.

The custom solution process involves six steps: 1. Customer gathers requirements. You (or your development team) gather all the requirements and get buyoff from the project sponsor and stakeholders. The time required for gathering the requirements depends on the complexity of the custom solution. 2. Customer creates High Level Design (HLD) document. You create and submit for review your version of the SharePoint Online HLD document. Your service delivery manager (SDM) then opens a Configuration Request (CR) and gives you the corresponding CR number. You must include the CR number when submitting the HLD document to Microsoft. 3. Microsoft reviews the HLD document. Microsoft reviews and responds within five business days after you submit your HLD document. We recommend that you don’t begin development work until Microsoft reviews and approves the HLD to allow feedback to be incorporated into the development. Microsoft doesn’t accept any customized code for review and testing until formal approval of the HLD. 4. Customer develops custom solution. After Microsoft approves your HLD document, you start developing your custom solution. 5. Customer tests, validates, and then packages custom solution with MSOCAF. You must then perform the following tasks in this order:

 Test the custom solution on-premises in an environment that matches the current SharePoint Online environment, including tests for scale and performance.  Use MSOCAF to:  Validate the custom solution code.  Test the deployment to your test environment.  Roll back the test deployment  Conduct any manual test cases applicable to the custom solution that are not included in MSOCAF. You build the deployment package, which consists of all solution documentation and all code components. You must submit the deployment package to Microsoft using MSOCAF at least 15 business days prior to the business day on which you want to deploy the custom solution, to allow for testing and validation by Microsoft. 6. Microsoft reviews, validates, and deploys. Microsoft reviews the custom solution, testing the code in a lab environment to confirm that the custom solution is supportable and matches the details of your HLD document. Microsoft validates the custom solution with manual tests chosen based on the solution type.

Note: Third-party custom solution licenses are needed at this point (if applicable) in order to proceed with pre-production and production deployment.

The following table breaks out the process and lists the development tasks for creating a custom solution and identifies who is responsible for each of them.

Custom Solution Process

Development Task MSF Process Model Phase Responsible Group Gather requirements Envisioning and planning Customer Create the High Level Design Planning Customer (HLD) document Submit the HLD document Planning Customer HLD document review Planning Microsoft Develop the custom solution Developing Customer Test the custom solution Stabilizing Customer Create the deployment package Deployment Customer Validate and submit the Deployment Customer deployment package Custom solution review Deployment Microsoft Custom solution deployment Deployment Microsoft

Microsoft considers each deployment in a Change Advisory Board meeting. Deployment occurs first in the pre-production environment (PPE). In parallel with Microsoft validation in the PPE, you have five business days to review the custom solution in the PPE, and sign off for deployment to the production environment. Deployment in the production environment occurs during a scheduled change window. For deployment outside of a normal change window, a service-level agreement (SLA) exemption waiver is required. For more information about an SLA exemption waiver, see Service-Level Agreement

Exemption Waivers. After your custom solution is deployed, Microsoft performs the validation steps you provided and then contacts you to perform any post-deployment actions. Timeline of the Custom Solution Process There are several key milestones, shown in the following table, which must be met to ensure the successful deployment of a custom solution to the PPE and production environment. Keep in mind that you must plan development and deployment dates accordingly for the custom solution process to succeed.

Timeline of the Custom Solution Process

Action Timing Customer submits the HLD document through the service delivery manager (SDM). Microsoft reviews the HLD document. Within 5 business days* Customer notifies the SDM of intent to submit custom solution deployment package, and receives a Configuration Request (CR) number. Customer submits custom solution deployment package. Microsoft reviews custom solution deployment Within 4 business days** package. Remove CR solutions within 5 business days** Independent software vendor (ISV) solutions within 5 business days** Microsoft deploys custom solution to PPE, if Within 3 business days approved. Customer validates the deployed custom Within 5 business days solution in the PPE. Microsoft deploys custom solution to Within 3 business days of customer validation of production. PPE***

* Assumes that Microsoft requires no additional information from the customer to process the review. ** Requires prior approval of the HLD document and a valid CR number for online submission. *** herflinkService-Level Agreement Exemption Waivers. Step 1 – Gather Requirements You first gather requirements from all relevant stakeholders: developers, support personnel, testers, and end users. When you factor in all of the requirements, it’s important to consider scale (for example, multiple web front-end servers) and performance (such as page load time and latency). Your requirements influence both how the code is developed and how it is tested. If you have multilingual requirements, the requirements for unit testing should specify that testing is performed in each localized language. SharePoint Online uses language packs, master pages, page layouts, resource files, and administrator interfaces that are specific to a locale. In some cases, you must ensure that the custom solution renders correctly when the page is read right to left or for a language that contains double-byte characters. You don’t need to submit a formal statement of requirements to Microsoft. However, specific constraints related to such factors as performance, scale, and language should be noted first in your HLD document and later in the test plan. Step 2 – Create and Submit High Level Design Document You create your HLD document, which presents information about the proposed custom solution, using the current version of the SharePoint Online HLD document. You then submit your completed HLD document to Microsoft for review and approval prior to code development. Before starting to implement the custom solution, your development team must use your HLD document to detail both the logical and the physical architecture of the proposed custom solution. The HLD document must also contain information about how the custom solution is implemented, how any configurations are managed, and whether there are dependencies on other custom solutions, third- party components, or external systems.

Security Note: Your development team should not proceed with any custom solution development work before Microsoft approves the HLD document. If the development team proceeds and the design is rejected, it could lead to time lost in the overall development cycle and potentially a delay in deployment of the custom solution. If the custom solution plan includes third-party

components that are to be purchased as part of the custom solution, we recommend that you purchase these components after the HLD is reviewed. If usage patterns, audience, hours of usage, or similar characteristics are likely to change as a result of a new custom solution, include that information in your HLD document so that resource considerations can be taken into account in the design phase, rather than during testing or after production deployment. Customer Responsibilities  Submit the completed HLD document to Microsoft through the SDM using a CR.

Important: The HLD document that you submit must follow the current HLD. Otherwise it will be rejected.  Wait for Microsoft to review and approve your HLD document before writing any custom code or buying licenses for a third-party solution.

Submit the HLD Document Wait for Microsoft to review and approve your HLD document before writing any custom code or buying licenses for a third-party solution.

Note: If your custom solution plan includes third-party components, you must submit a trial version of those components with your HLD document.

Note: Once an HLD document has been approved by SharePoint Online, the associated CR is closed as completed and cannot be re-opened. Revisions made to an approved HLD document should be submitted to SharePoint Online for review under a new CR number.

Step 3 – Microsoft Review of High Level Design Document Microsoft reviews your HLD document with you to provide an initial evaluation of your proposed custom solution. The goal of the HLD review process is to provide Microsoft with the opportunity to provide feedback on your proposed design. The review ensures the design doesn’t violate the published

custom solution policy and that it can be hosted within the SharePoint Online hosted environment. The review also gives Microsoft an opportunity to suggest alternative solutions. The HLD review has the following goals:  Provide Microsoft with the opportunity to suggest an out-of-the-box solution or a previously evaluated third-party solution instead of custom development.  Provide feedback to ensure that the design implementation follows established best practices and receives guidance from experienced SharePoint developers.  Evaluate the design to determine whether it is supportable within the hosted SharePoint Online environment, and whether it poses any risk to the existing environment or the ability of Microsoft to meet the SLA.  Determine whether additional hardware is needed to support the custom solution. For more information, see Hardware Evaluation.  Identify potential performance issues in the design phase, rather than during testing or after production deployment.  Minimize the likelihood that you will need to rewrite or change your solution when service packs and future versions of the product are released. Microsoft has five business days to respond to your HLD document. If the review will require a longer period than the standard five business days, Microsoft notifies you and provides an estimate of the additional amount of time required to review your HLD document. Microsoft Responsibilities  Return an evaluation of your HLD document within five business days of receiving the document, or immediately notify you if more than five days will be needed for review.  Evaluate your HLD document against the existing infrastructure and resources, and notify you if your custom solution design requires changes.  Provide feedback if problems with the solution design are discovered. Customer Responsibilities  Designate a developer resource to respond to questions or concerns, so that Microsoft can conduct the review within the window of five business days.

Hardware Evaluation The HLD review is performed based on your current load and hardware configuration. In some cases, an HLD review might reveal the need for additional hardware or upgraded components, especially if Microsoft anticipates that your custom solution will generate a high load or require significant resource consumption. For example, a multipart custom solution may require deployment of additional servers, or upgrades to existing servers, to meet performance expectations and service-level agreement (SLA) requirements. In certain cases, other resources and operational support may be necessary.

Important: Microsoft reserves the right to charge for any additional hardware required (which could delay the deployment of the custom solution by three months or more) or else reject any custom solution that requires the addition of hardware or resources above and beyond what is already provisioned for you. Step 4 – Develop Custom Solution You now begin development of your custom solution based on the approved HLD. For guidance, best practices, and more details about custom solution development, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). Once your HLD document is approved, your development team can begin implementing the design. You’re responsible for developing or purchasing the custom solution, and for operating a development environment. To assist you in creating an environment that mimics the production environment, Microsoft provides the SharePoint Online Customer Build Guide.

Note: Contact and confer with your service delivery manager (SDM) before using the Customer Build Guide. Prior to development, you should check with Microsoft to determine whether any updates are scheduled to be installed prior to deployment of your custom solution. It’s your responsibility to ensure that development and testing are done using the appropriate version of SharePoint. Microsoft SharePoint 2010 updates are cumulative, so they can’t always be rolled back in a production environment after being deployed.

Important:

Development and testing must be done with the same SharePoint version, including the update levels, that’s installed in your SharePoint Online production environment. Other environmental factors that impact functional behavior should also be duplicated as closely as possible. These environmental factors include line-of-business applications and services that the custom solutions integrate with, such as applications, services, and domain trusts. Additionally, the test environment should have the same monitoring environment (Microsoft System Center Operations Manager) as the SharePoint Online environment. Follow these guidelines during custom solution development:  Use a source control system for storing and tracking all the custom solution artifacts.  The code must not require full administrative privileges to run.  The custom solution should be as self-contained as possible. Any dependencies should preferably be within the custom solution itself.  Minimize the need for manual configuration changes during deployment.  Build the custom solutions in a way that allows for upgrading components of the solutions rather than retracting and redeploying new versions. Clarify any questions with your SDM before beginning a full-scale production development. Customer Responsibilities  Integrate MSOCAF into the development life cycle, and use the report of errors, exceptions, and warnings in MSOCAF to improve the code.

Note: It’s not necessary to resolve all warnings, but we recommend doing so.

Step 5 – Test, Package, and Validate with MSOCAF You’re responsible for fully testing and validating the custom solution in the farm environment. You must use MSOCAF to validate the code and test the deployment and rollback of the custom solution in your test environment. To ensure that the solution is designed and coded using established best practices, you must also conduct any appropriate manual tests specified in the SharePoint Online Custom Solution Test Cases document and submit the results in the deployment package using the SharePoint Online Test Results template. For more information about testing and validation for developers, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). You must validate your custom solution code using MSOCAF. Install the MSOCAF application in the development/test environment using a Local Administrator user account. For more information, see About MSOCAF. You must ensure that the solution is fully tested before submitting it for review and deployment by Microsoft. The testing environment should match the SharePoint Online production environment. Testing should take place in a farm environment (with two web front-end servers and separate servers for service applications and content databases) rather than a standalone environment. Insufficiently tested code is a risk to your entire SharePoint Online environment. If Microsoft has sufficient concern that you haven’t adequately tested the code, the code is rejected during the review process.

Important: You’re responsible for testing the solution, whether it is purchased from a third-party vendor or developed by your development team, before submitting it for review and deployment by Microsoft. We suggest development team use a separate, dedicated test team that is familiar with your production version of SharePoint. Testing must cover the entire solution life cycle, including:  Installation  Deployment or upgrade  Activation  Creation of content

 Editing of content  Expiration or deletion of content We recommend that the development team perform a full formal test pass first and then hand off to a separate customer test team to minimize the number of defects. To learn more about internal testing of custom-developed code for SharePoint Online and how to document it, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans).

Limitations Microsoft does not offer a customer-accessible testing environment. It’s your sole responsibility to test all components of the solution and maintain a test environment. These tests should include, but not be limited to:  Functionality  Performance  Stability  Scale  Full unit testing The pre-production environment (PPE) that Microsoft provides for you to perform functional validation of custom solutions is not a substitute for a test environment. For details about the PPE, see Pre- Production Environment Validation. If a custom solution depends on integration or communication with services, data, or systems that are unique to your corporate environment, Microsoft is unable to validate this functionality. However, when you evaluate code in the PPE, you can validate whether these forms of integration are working as expected. When you perform these types of integration tests, we recommend that you provide and use connections to a user acceptance test (UAT) version of your service, data, or system to avoid negative impact to the production environment. Microsoft Responsibilities  Provide guidance about how the production environment is built, so you can create test environments that adequately mimic the production environment.  Provide guidance about all installed builds and updates within the SharePoint Online environment. Customer Responsibilities  Build and maintain development and test environments.

Package the Custom Solution MSOCAF validates that the custom solution deployment package has the required directory structure and artifacts needed for deployment. For complete information about what the deployment package must contain, the required directory structure, and other aspects of deployment packaging, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). Customer Responsibilities  Package all the relevant artifacts needed for the deployment in a custom solution deployment directory.  Provide comments in the Justification field to explain any false positives.  Run the MSOCAF report with the public symbol file information present, which allows MSOCAF to generate the report with line number references.  Include your version of the MSODeploymentGuide for your custom solution in the deployment package.

Important: The deployment guide you submit along with your custom solution must follow the current deployment guide template. Otherwise, the deployment package will be rejected.

When custom code development and testing are finished, your development team builds the deployment package and analyzes it using MSOCAF. This package must contain all of the solutions files, the deployment guide, the MSOCAF report, and other package components. You must then submit the deployment package directly from MSOCAF to Microsoft to be tested and reviewed before it can be deployed to the production environment. Testing by Microsoft does not begin until the final code and all documentation have been received.

Note: The deployment package must include a full documentation set, whether you’re submitting a new custom solution or an update to an existing custom solution.

When you prepare the solution packages and the documentation for the custom solution package, it’s important to keep in mind that all custom solution packages are first deployed to the PPE and then to both a primary and a secondary data center (maintained for disaster recovery). When the secondary data center is set up, the content databases are not attached to the SharePoint farm. In the event that

service is interrupted in the primary data center, all necessary services for deployment of custom solutions are functional and running in the secondary data center. If the custom solution contains any components that must be run, installed, or deployed in a specific environment, the deployment instructions that you supply should note this. For example, if you are creating scripts or a Feature receiver that creates a site collection, list, or custom database, then the deployment instructions should include the following points:  The script or Feature receiver should only be run after it’s in the farm.  The custom solution must be fault-tolerant; in other words, it should work in all conditions whether or not the site collection, list, or custom databases exist in that environment.

Scheduling the Deployment Each customer receives a change window calendar that contains the available windows during which custom solutions can be deployed. You should be aware of the scheduled change windows when you submit the custom solution deployment package for review, and begin scheduling a deployment at least 15 business days in advance.

Note: This scheduling assumes your HLD document is approved. First you ask the service delivery manager (SDM) to submit a Configuration Request (CR) before you submit the deployment package. Then you submit the deployment package at least 15 business days before the change window that you want to target for deployment. This lead time allows Microsoft to schedule resources, build a lab environment in preparation for testing, and then perform the testing. For more information about designated change windows, see Change Window Calendars. Customer Responsibilities  Ask your SDM to submit a CR (with “code drop” in the title) before submitting the deployment package. The SDM then opens a CR and provides you with the CR number.  If you’re scheduling the deployment of multiple interdependent custom solutions, the CR for each must specify the sequential order of deployment (for example, Governance 1/2, Governance 2/2).

Microsoft Responsibilities If you’ve specified the sequence of deployment for multiple interdependent custom solutions, Microsoft deploys them in that order.

Submitting the Deployment Package You must submit the deployment package to Microsoft through MSOCAF. The CR number is required during the submission process. Customer Responsibilities  Always submit a complete deployment package, even when resubmitting the same custom solution.  Provide details about what has changed, if you have an update to either a new or existing custom solution.  Submit details about rolling back or installing the previous version of the custom solution.

Important: Do not submit any custom code by email. It will not be accepted. Many spam filters and malware applications will block or delete executable files (like .bat files). Follow the submission guidelines provided in this article to submit your custom solution.

MSOCAF Submission Troubleshooting

 In the event of a submission failure in MSOCAF, the tool creates a local submission package that you can submit to Microsoft manually with the assistance of your SDM. For any additional troubleshooting or questions about MSOCAF, contact [email protected].

Deployment Guide In the MSODeploymentGuide, you must include details about:  How to install all of the custom solution deployment package components  All architecture diagrams that are related to the installation of the custom code.  Procedures for validating that the solution packages and the solution as a whole have been properly deployed.

Important: You must submit the most current deployment guide template. Otherwise the deployment package is rejected. In order for the deployment guide to be accepted by Microsoft:  It must be completely self-contained. For example, there can’t be any references to email threads or other documentation not in the guide, or Microsoft will reject your custom solution package.  Don’t include an email address for receiving evaluation results. Results will be sent to the customer- specified email address on file.  You must include a list of prerequisite software and any open-source software to be used in your custom solution.  You must include detailed verification steps in the deployment guide so that the SharePoint Online operations team can verify that the solution is working as expected post-deployment. This includes listing any telltale signs, global assembly cache (GAC) versions, and screen shots of the environment that indicate successful deployment.  If you’re using third-party solutions, pointers to the vendor's installation documentation are usually not suitable because they are typically written for general deployment scenarios. You must include in the deployment guide all specific steps and procedures that are required for proper installation of the third-party solution.

Deployment Manifest MSOCAF includes features for testing the automated deployment and rollback of custom solutions in your test environment. These features require the creation of a deployment manifest. Deployment or rollback can occur only for the components specified in the deployment manifest file, an XML file that captures all of the deployment instructions. You must create your deployment manifest using the Custom Solution Deployment Manifest. There are four supported deployment actions for custom solutions in the SharePoint Online environment. Understanding the differences among these actions is critical for understanding the steps needed to deploy or change custom solutions.  Deploy – Installs a custom solution.  ReDeploy – Uninstalls (removes) a custom solution completely, and then reinstalls (redeploys) it. This new deployment could be the same version, or a newer version.

 Upgrade – Changes an existing custom solution to the next version. Certain elements of the custom solution are altered or replaced, but the existing custom solution is not uninstalled.  Remove – Completely uninstalls a custom solution. Step 6 – Microsoft Review, Validation, and Deployment During this step, Microsoft:  Reviews your custom solution to ensure that it is supportable.  Checks that it matches the details of your SharePoint Online HLD document.  Tests it in a lab environment at Microsoft. At the same time, you have the opportunity to test the custom solution in the pre-production environment (PPE). The final steps in the process include Final Change Advisory Board review, preparation, and deployment to the production environment.

Timeline for Review and Deployment by Microsoft Microsoft begins analysis and pre-production testing after you submit the custom solution deployment package. Here’s how a typical deployment package review works: 1. Engineering review: Testing and validation. Microsoft reviews your submitted custom solution deployment package. This usually takes up to four business days. It includes testing the code in a lab environment at Microsoft and validating the custom solution using MSOCAF. For more information, see Engineering Review by Microsoft. 2. PPE deployment decision. The SharePoint Online engineering team approves or rejects deployment of your custom solution to the PPE. If Microsoft rejects a deployment, you can fix the solution and resubmit it. Microsoft will review the new submission within four days. For more details, see Resubmission Policy for Custom Solution Deployment Packages. 3. PPE deployment. The approved custom solution deployment package is deployed to the PPE. For information about the PPE, see Pre-Production Environment Validation. 4. Your PPE review. You have five days to review the custom solution in the PPE. You then approve or reject deployment to the production environment. Only after you approve the custom solution can Microsoft deploy it to the SharePoint Online production environment. For more information, see Pre-Production Environment Validation.

5. Production Change Advisory Board review. Microsoft reviews the testing and validation results after both the SharePoint Online engineering team and you have approved deployment to the production environment. For more information, see Production Review. 6. Operational deployment preparation. The preparation for production deployment typically takes from one to three business days. Deployments that fall outside of a Friday change window require a service-level agreement (SLA) exemption waiver. For more information, see Service-Level Agreement Exemption Waivers. 7. Production deployment. Microsoft deploys your custom solution deployment package into production. For more information about the deployment window, see Production Environment Deployment. The following figure shows the timeline for the custom solution deployment process and includes the following key milestones:  Initial code submission (code drop)  Code review timeline (four business days)  PPE deployment timeline (three business days after code is approved by Microsoft)  PPE customer approval timeline (five business days after code is deployed to the PPE)  Production deployment timeline (three business days after customer PPE approval is received)

Security Note: The milestone timeline assumes the code drop is approved during the initial submission. If the code drop is rejected and you have to submit a re-drop of the custom solution, the timeline for PPE deployment starts three business days after Microsoft approves the code re-drop.

Engineering Review by Microsoft The SharePoint Online engineering team uses MSOCAF and manual tests to review the following items in a lab environment at Microsoft, depending on the custom solution. The engineering review:  Confirms that the custom solution matches the details of the approved HLD document.  Evaluates solution packages and installation/uninstall scripts.  Checks for memory leaks.  Determines whether error handling and exception handling are sufficient.  Ensures that the code falls within the custom solution policy.  Ensures that elevated privileges follow established best practices.  Checks compatibility with the current production version of SharePoint.

 Tests for security vulnerabilities.

Note: There are custom solutions for which some of these tests do not apply.

This testing and analysis evaluates the following:  Supportability of the code on your architecture in the SharePoint Online hosted environment.  Dependencies that may pose conflicts or risks.  Quality of error handling when dependent components aren’t available to the code.  Adequacy of the documentation, ensuring that it describes your custom solution, details all dependencies, and demonstrates that you’ve done adequate functional unit testing. Core functionality is occasionally tested by Microsoft, including the deployment footprint on the installation, to ensure that the application doesn’t make an unnecessary or potentially harmful change to the service. There are also tests to verify that, when a feature is disabled, the page still renders correctly. The SharePoint Online engineering team also tests that web.config files are correctly updated when your custom solution is activated, and that changes revert when the custom solution is deactivated. Aesthetic aspects of your custom solution, such as the user interface, aren’t reviewed. It’s your responsibility to ensure that your custom solution meets the requirements and fulfills any anticipated needs. The code in your custom solution is not formally unit-tested. If your custom solution has dependencies on external services, such as web services, data, or line-of-business systems that are not available in the lab environment at Microsoft, Microsoft cannot test the custom solution. In these cases, we review the code and try to establish that you have performed adequate testing, based on your documentation. We encourage you to test these dependencies within the PPE prior to the production deployment.

Rejected Custom Solution Submission

If for any reason a custom solution is rejected, Microsoft gives you a review report explaining why the submission was rejected. To prevent additional rejections, if there is anything in the report that is unclear, or if for any reason you’re unsure how to resolve the issues with the submission, we encourage you to coordinate with your service delivery manager (SDM) to schedule a call with the SharePoint

Online Custom Solution Review Team. This ensures that you don’t repeat custom solution submission errors and prevents unnecessary delays in the deployment of your custom solution. Microsoft Responsibilities  Determine the scope (small, medium, large, or extra-large) of your proposed custom solution as detailed in Custom Solution Scoping Policy.  Test the deployment process and evaluate installation, rollback, and test documentation.  As far as possible, validate the basic functionality of your new custom solution via the validation (“smoke”) test that you provide. This may not be possible if a dependency (web service, data, or system) is unavailable in the lab environment at Microsoft.  Provide you with a report if a submission is rejected.

Important: You’re responsible for conducting any formal unit testing of the code.

Pre-Production Environment Validation Deployment to the PPE usually occurs approximately three business days after you submit the package to Microsoft, assuming a successful engineering review and Change Advisory Board approval.

Note: Deployment to the PPE cannot occur on Fridays, which are reserved for deployment to production. The PPE is a scaled-down replica of the production environment with a matching configuration. It is intended only for performing final user acceptance test (UAT) and validation (“smoke”) testing of your custom solution. It enables validation of custom solutions prior to deployment to the actual production environment, as well as validation of existing custom solutions against a new version of SharePoint (including update, service pack, or major release). The PPE is not subject to the service-level agreement (SLA) or the availability key performance indicator (KPI). The virtualized PPE is designed to have the same logical architecture as the production environment, with the following restrictions:  You can replicate content from the production environment to the PPE for custom solution validation. You can select your root site, up to two site collections, and a custom database to be replicated to the PPE.  The total volume of content cannot exceed 250 gigabytes (GB).  The total number of content databases per web application cannot exceed 2.  Up to 250 concurrent users can access the PPE at the same time.  By default, email is not enabled in the PPE to prevent inadvertent spamming to security groups and individual users during testing. You can request to have email enabled in the PPE by submitting a Configuration Request (CR) through your SDM.

Note: The PPE is not a substitute for a customer-hosted test environment, and is not intended for scale and performance testing. The custom solution doesn’t become available to you in the PPE

until after you submit the deployment package and it has passed review by the SharePoint Online engineering team. After Microsoft deploys the solution to the PPE, you can access the custom solution to do the following:  Validate the custom solution in a UAT environment before production deployment.  Provide access for designated users to the custom solution prior to going live in production.  Validate an existing custom solution (one that is currently in production) against SharePoint Online upgrades or updated custom solutions. This is done to identify any problems that should be expected while the solution is deployed.  Ensure that any new ports are opened, and that PPE servers have sufficient access (in cases of limited IP range access) to your data sources or systems as appropriate.

Security Note: After PPE validation begins, if it’s necessary for you to deliver a new version of the code, Microsoft cancels the original CR used for deployment and you must open a new CR. This is necessary to ensure version control of your custom solution. Keep in mind that this places deployment during the targeted change window at risk. After you fully validate your custom solution in PPE, you must sign off via email to the SDM so that Microsoft can proceed to deploy your custom solution in the production environment according to the change window calendar.

Note: PPE is not a production environment. Therefore, PPE incidents are always prioritized below incidents that impact production and are given a Severity D ranking.

Microsoft Responsibilities  Provide a dedicated, hosted PPE to validate the custom solution.  Follow the MSODeploymentGuide instructions that you provide, which includes running automated scripts to deploy the custom solution to PPE.

Note: Third-party solutions are also deployed in this manner.

 Test that your custom solution is successfully deployed to the PPE using the post-deployment validation and test process that you’ve supplied in the deployment guide.  Provide data connections to existing systems or services within a UAT scenario.  Maintain the PPE to ensure that it replicates the current settings and configurations in production. Customer Responsibilities  Verify that your custom solution is working as expected, within the window of time specified in the custom solution project schedule.

Production Review After you and the SharePoint Online engineering team sign off for production deployment, you submit the custom solution to the Change Advisory Board for consideration for production deployment. If the Change Advisory Board rejects the deployment, deployment is canceled for that change window. Microsoft provides rationale for the rejection, and contacts you to begin remediation. This is done first by email, and if necessary, with follow-up meetings. After remediation, Microsoft schedules another round of testing and deployment. For more details about the Change Advisory Board process, see the Change Management.

Production Environment Deployment After final approval by the Change Advisory Board, Microsoft prepares to deploy your custom solution to the production environment during an upcoming change window. These change windows are dedicated to the deployment of tested and approved custom solutions, and are usually scheduled for Friday evenings. The production environment deployment includes:  Installation of the solution packages (.wsp files) to the SharePoint Online environment, as outlined in the deployment guide that you supplied.  Testing the deployment based on the validation instructions that you also supplied in the deployment guide, to ensure that the custom solution is successfully deployed.

Note: Deployment does not include any further activities by the SharePoint Online operations team. Microsoft doesn’t do any performance or functional testing in the production environment. If there are tests that you want Microsoft to perform, you should include them in the deployment guide. If your custom solution requires extensive testing after deployment, it’s your responsibility to provide the resources to perform this work. If negotiated in advance, a SharePoint Online team member will assist for the duration of the window to help make minor adjustments to the deployment. After the change window expires, all further updates to your custom solution that require operational deployment must be approved by the Change Advisory Board. Microsoft Responsibilities  Follow the deployment guide instructions that you provide to Microsoft, which includes running automated scripts to deploy your custom solution to the production environment.

Note: Third-party solutions are also deployed in this manner, and also require deployment guide instructions.  Test that your custom solution is successfully deployed to the production environment using the Release Verification steps that you provide in the deployment guide.  If tests show that the deployment is unsuccessful, roll back your custom solution by following the Solution Retraction steps that you provide in the deployment guide.  Notify you when the custom solution deployment is complete and whether it’s successful or unsuccessful.  Respond immediately to any notification that you give Microsoft of corruption or problems with your custom solution as described in Break-Fix Policy.

Important: There is a risk of data loss if a rollback is required. You must notify Microsoft as quickly as possible, to minimize this loss of data. Customer Responsibilities  Make resources available during the change window to test the functionality and confirm the performance of your custom solution, as needed.

 Open a Service Request (SR) with the Office 365 support service desk ([email protected]) as soon as possible about any corruption or problems with your custom solution.

Custom Solution Policies Topic Last Modified: 2015-03-09 Custom Solution Deployment Maximum Microsoft allows a maximum of two distinct custom solutions to be in flight at any given time, whether it’s being deployed or retracted. In flight is defined as the period from scheduling pre-production environment (PPE) deployment until completion of the production environment deployment. In the case of a retraction of your custom solution, it’s considered in flight until it has been fully retracted from both PPE and production environments. Additional custom solutions can be submitted for review, but none will be scheduled for deployment until one of the solutions already scheduled has been deployed. If there are dependencies between custom solutions, you must specify them. For more information about configuration policies, see the SharePoint Online Configuration Request Guidelines. Service-Level Agreement Exemption Waivers Requests that might impact users due to potential downtime or performance degradation are normally scheduled for implementation during a scheduled Friday change window. For custom solution deployments that impact users, this schedule can be modified if:  You provide a service-level agreement (SLA) exemption waiver approving implementation outside of their scheduled change window.  The deployment takes place during a business day between the hours of 10:00 and 18:00 Pacific Time. You must supply Microsoft with an SLA exemption waiver in order to deploy to the production environment outside their normal Friday change windows. If you are willing to grant an SLA exemption so that your custom solution deployment can be implemented ahead of the next change window, you should complete the Microsoft SharePoint Online SLA Exemption email template in order to notify your service delivery manager (SDM). If a custom solution package deployment is estimated to take longer than a scheduled change freeze window, or your custom solution package contains a long-running script, Microsoft might require an

extended SLA exception waiver to account for the variable deployment or run time of the script. The start date and finish date of the SLA exception waiver is determined by Microsoft after the PPE deployment is completed and a more accurate deployment or run time is evaluated. A customer- approved SLA waiver must be received before the production deployment can be confirmed. Custom Databases Microsoft enforces the following policies regarding the use of custom databases:  If you want to deploy your own custom solutions, you’re allowed one custom database for that purpose.  You’re allowed one additional custom database for each approved third-party custom solution that requires a custom database. For a full list of all approved third-party solutions, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). MSOCAF Compliance Policy With every release, Microsoft provides a notification period that you can use to ensure that custom solutions will be compliant with the upcoming set of new and updated MSOCAF rules. As soon as new rules are communicated, we recommend that you familiarize yourself with them and validate all new custom solutions or updates to existing custom solutions against these rules to avoid any issues or escalations after the compliance date.

Critical MSOCAF Releases Microsoft sometimes releases a critical rule when a major risk or issue is identified that needs to be fixed immediately, including problems that impact:  Performance  Scalability  Security  Stability You’re asked to re-engineer all currently deployed custom solutions retroactively within 30 days of notification, if any of your custom solutions are impacted by this critical rule. For customers that are unable to fix the impacted custom solutions within 30 days of notification, Microsoft might decide to

either roll back those custom solutions to prevent major service impact, or suspend the SLAs for those customers.

Important: You must make new custom solutions compliant with any critical rule immediately after that rule is released. MSOCAF Compliance Periods Only critical MSOCAF rules are enforced retroactively. Retroactive enforcement means that you’re required to address MSOCAF failures and exceptions in all of your previously deployed custom solutions. You’re required to address MSOCAF failures and exceptions only when you submit new or updated custom solutions. The following table outlines when your custom solutions must be compliant with the latest MSOCAF release. Compliance Period for Custom Solutions

Custom Solution Type Compliance Period Notes New custom solution (non- 90 days All MSOCAF failures and retroactive) exceptions must be fixed prior to submitting new custom solutions. Example: In July of 2014 Microsoft communicates all the new quarterly rules that will be enforced starting in October of 2014.

Custom Solution Type Compliance Period Notes Existing custom solution 90 days You must run MSOCAF with the updated to comply with newly-released quarterly rules quarterly rules (non- against your existing custom retroactive) solutions, and fix all MSOCAF failures and exceptions prior to submitting any update. Example: In July of 2014 Microsoft communicates all the new quarterly rules that will be enforced starting in October of 2014. Existing custom solution 30 days You must run the newly-released updated to comply with critical critical MSOCAF rules against all rules (retroactive) of your existing custom solutions, and remediate any failures and exceptions within 30 days for the impacted custom solutions. Custom solution credits aren’t deducted from any custom solutions that are re-submitted because of a critical release. Example: On July 1, 2014, Microsoft communicates a new critical rule release. You must submit all of your existing custom solutions impacted by this rule by August 1, 2014 to prevent putting your environments at risk.

Custom Solution Type Compliance Period Notes Existing custom solution At every SharePoint product Approximately every three years, upgraded for new product release Microsoft will upgrade all of your release (retroactive) SharePoint environments to the next SharePoint product release. Prior to a SharePoint upgrade, you must upgrade all custom solutions and fix all failures and exceptions detected in MSOCAF before submitting them to Microsoft.

Custom Solution Scoping Policy After you submit the deployment package, the SharePoint Online engineering team reviews the scope of the planned solution. The determination of its scope, or size—small, medium, large, or extra-large—is based on the amount of code and number of solution packages (.wsp files) that are included in the custom solution deployment package. For more about solution packages and .wsp files, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). The solution size is determined by the highest threshold factor for the solution, as shown in the following table. For example, if the package consists of 2 .wsp files but 2,000 lines of code, then it is of medium size. Or, if there are 3,000 lines of code, but 9 .wsp files, then it is extra-large. Custom Solution Package Sizes

SOLUTION THRESHOLD FACTORS CUSTOM SOLUTION CUSTOM SOLUTION CREDITS (.wsp- CREDITS (Deductions) related) Size Lines of Code* Number of .wsp Files Deducted from Total Credits Small 0 to 1,000 1 to 2 1 Medium 1,000 to 3,000 3 to 4 1

SOLUTION THRESHOLD FACTORS CUSTOM SOLUTION CUSTOM SOLUTION CREDITS (.wsp- CREDITS (Deductions) related) Large 3,001 to 6,000 5 to 8 2 Extra-large 6,001 or more 9 to 12 3

Important: For a custom solution that is categorized as large or extra-large, if you must resubmit any part of the custom solution package for any reason during the review, validation, or production deployment, then deployment is postponed to the next scheduled window (typically two weeks).

Note: For a large or extra-large solution, Microsoft charges you additional credits, even though technically this is only one solution. Also, due to the complexity of a large or extra-large solution, it may be the only custom solution deployable in a given change window.

In general, you can anticipate the solution size based on the criteria from the previous table. However, a solution might be classified differently despite the amount of code or number of .wsp files when it:  Is more complex than normal.  Contains dependencies involving a significant number of external systems.  Processes a large amount of user-provided content.

When you submit a complex custom solution, Microsoft notifies you if additional time is necessary to complete the review. If you’re designing a custom solution that will require more than 10 .wsp files, your development team should reconsider its architecture. We recommend that you consider breaking up a large project into multiple phases that are evaluated and deployed at different times. It’s difficult to manage and deploy so many solution files within a single deployment window, and your custom solution risks rejection because of the level of complexity. Policy for Updating Custom Solutions When you provide an update to a custom solution that’s deployed in the production environment, you should follow the steps described in Overview of the Custom Solution Process. When changes to the code are minimal, this process often proceeds quickly. Customers must provide clear solution deployment steps and solution retraction steps for the updated custom solution in your copy of the MSODeploymentGuide. For example, a new .wsp redeployment may require the previous .wsp file to be uninstalled to avoid a new .wsp file automatically updating the existing .wsp file. When you submit an update to a custom solution or to its documentation, it’s very important to complete the Changes in This Release section of the SharePoint Online HLD document for the deployment guide. It is also important to provide details about both the uninstall and rollback processes. In addition, you should call out any problems that might be expected with the update. When you update an existing custom solution, the existing documentation must also be updated. If the design has changed and now requires a feature enhancement or other change to functionality, you must first submit a new HLD document. This should be submitted under a new Configuration Request (CR) number. The CR associated with the previously approved HLD document should not be re-opened. If existing custom code is being updated only to address bugs, and there are no fundamental design changes, no HLD document is necessary and you only need to update the documentation in the deployment package. Microsoft Responsibilities  Determine whether validation of the update can be completed more quickly than the normal turnaround time, and, if so, inform the customer.

Customer Responsibilities  Provide complete documentation, as described in SharePoint Online Custom Solution Developer's Guide (Dedicated Plans).  Understand that the SharePoint Online engineering team will take your updated custom solution through the entire validation process. (This process might be somewhat shorter for an update than for a new custom solution.) Resubmission Policy for Custom Solution Deployment Packages If you want to update the deployment package after a custom solution has already been approved for PPE deployment, you can resubmit your custom solution. The following requirements apply when you ask Microsoft to receive an updated deployment package:  When you resubmit a custom solution, you must include the entire deployment package, and then document the changes that have been made since the initial drop, including a traceability matrix and a statement of the impact of the change. If you fail to provide this information, Microsoft rejects the solution, and deployment is delayed. If these conditions are met, Microsoft reviews the solution within 4 business days.  For large and extra-large custom solutions, the custom solution deployment package can’t be deployed in the original change window after it is resubmitted. It’s not feasible for Microsoft to review such a large custom solution deployment package by day three after the package is submitted.  You must perform an MSOCAF validation of the entire deployment package again, including all updates, prior to resubmission to Microsoft.  If the resubmission modification constitutes a design change, you must submit an updated HLD document to reflect the design change.

Note: Microsoft reserves the right to reject a delivery if the design deviates fundamentally from the approved HLD. These timeframe references are based on the review and deployment schedule covered in Timeline for Review and Deployment by Microsoft. Break-Fix Policy The break-fix policy is used if you identify a problem in a custom solution that is deployed to the production environment, whether the problem occurs immediately after deploying your custom solution, or at some later time. Examples of such a problem include:  The look and feel of a site needs to change.  The site font is the wrong color. For a detailed description of the process for escalating post-deployment issues that are related to custom solutions, see Appendix C: Escalating Custom Solution Post-Deployment Issues. If this happens, you can:  Remove the custom solution entirely. The Configuration Request (CR) you submit must specify that your custom solution is to be removed as opposed to simply rolled back to the previous version. You acknowledge and agree that the entire custom solution is removed, and not just one version of the solution, so all functionality of this solution is lost.  Roll back the custom solution to a previous production version (if available). The CR you submit must specify that the custom solution is to be rolled back as opposed to being removed entirely.  Wait until a fix can be deployed. Microsoft makes every effort to accelerate the testing of the fix, but doesn’t provide a shortened review period.

If the problem requires deployment of a fix, it’s generally handled in the same manner as other changes made to the production environment, as directed by the change management process. Microsoft makes all efforts to perform remediation as quickly as possible, but the change can’t be made until the first available negotiated change window that occurs after the code for the break-fix is complete.

Important: No changes will be accepted to your custom solution deployment package after you have signed off on PPE validation. If you decide to make any further changes to your custom solution, you must reschedule the deployment date to the following change window.

Microsoft treats the following problems with break-fix remediation:  Feature or functionality changes to existing custom solutions.  Errors that affect the visual presentation of data.  Errors that affect the display of content from a third-party solution.  A custom solution that doesn't work as expected. If the problem doesn’t meet emergency change criteria, you must submit the change through the regular custom solution process just like any other update.

Emergency Change Remediation For emergency changes that can’t wait for the next available change window, there’s a faster process. If a critical problem meets the Microsoft emergency change criteria described below, Microsoft accelerates the deployment of a fix to address the situation as quickly as possible. Emergency deployments aren’t restricted to a scheduled window, and all effort is made to negotiate the window between you and Microsoft. For this to happen, the problem must:  Impact the functionality of a custom solution deployed in your production environment.  Cause a significant and quantifiable business impact.  Impact availability or system stability.  Put information or the security of content at risk. If your custom solution affects the service, you should escalate the problem from your help desk to the Office 365 support service desk ([email protected]), with a joint troubleshooting session if the

root cause is unknown. Situations like these are why you need to submit adequate troubleshooting guides and rollback steps along with the other custom solution documentation.

Note: You must submit a CR if a code update is required. If the service is not impacted and the solution to this issue is known, then you must fill out a CR after the custom solution is fixed and fully tested on premises. Within one business day of receipt of the emergency custom solution deployment package, Microsoft provides you with an estimate as to the time required to deploy the code to production. The time that’s required to deploy depends on both the complexity of the code and the risk to the service. The emergency fix must also be deployed and signed off in the PPE prior to production deployment, as with any change. If the solution to the issue has an adverse impact on your user’s experience, or impacts the ability of Microsoft to meet its service-level agreement (SLA) for performance, stability, and availability to clients, Microsoft must take immediate action. This might include removing the code to return the environment to a stable state, or debugging the application and optimizing it for current load and stress conditions. If one of these situations occurs, Microsoft makes the best decision possible.

Important: The service availability SLA is suspended for any downtime that you incur during emergency change deployment. Customer Responsibilities  Notify Microsoft as soon as possible via Service Request (SR) when a problem is encountered.  If necessary, build an update to fix the problem, and provide standard documentation for Microsoft to deploy, validate, and roll back if necessary, as described in SharePoint Online Custom Solution Developer's Guide (Dedicated Plans).  Be ready to validate the fix immediately when Microsoft deploys it to both the PPE and production environment.  In the case of issues with a third-party solution, interact directly with the independent software vendor (ISV) to resolve the problem and keep SharePoint Online informed of all developments. Microsoft Responsibilities  Respond within one business day when notified by you of a problem within the environment.

 If the problem meets one of the emergency change criteria, take the request to the emergency Change Advisory Board.  Validate the proposed fix as quickly as possible, after you submit it. Platform Upgrades or Updating Impacts To ensure the stability and security of the SharePoint Online service, it might be necessary to update your environments. Some updates are both critical and time-sensitive, others are not. Microsoft performs some testing of updates (hotfixes and cumulative updates) and service packs to ensure a smooth deployment. However, Microsoft doesn’t test updates or service packs against deployed custom solutions. Microsoft deploys updates and service packs to your PPE a minimum of six weeks before the deployment of the updates or service packs to the production environment. Security update releases, such as the monthly security updates, are applied to the PPE and production environment with a shorter release turnaround due to the critical and time-sensitive nature of the updates.

Note: It’s your responsibility to perform any pre-deployment testing of updates or service packs against your custom solutions. Current update levels for the farm are available in your Reporting site, or you can contact your SDM for the latest update levels and planned updating for your environment. Microsoft notifies you at least six-to-eight weeks before deploying any updates or service packs to the production environment that are not critical or time-sensitive. The notification contains the necessary links and information to update your development and test environments and to test existing custom solutions against the released update or cumulative update. You will rarely need to modify your custom solutions because of an update or service pack if you follow the best practices that are presented in SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). Microsoft Responsibilities  Test updates and service packs against the normal hosted environment to confirm that no problems arise and that the deployment process is successful.  If an update is critical and time-sensitive, notify you as soon as possible before deployment of the update.  Provide you with the PPE and production deployment dates of all updates and cumulative updates.

 For updates that are not critical or time-sensitive, deploy them to the PPE at least two weeks prior to production deployment.  If the update is not publicly available, provide a copy of the update on demand if the update is released and being distributed externally. Customer Responsibilities  Test the update or service pack against custom solutions in your test environment.  Contact Microsoft as soon as possible if any problems related to updates are found.  Provide Microsoft with the necessary custom solution updates and documentation to mitigate any problems when the update or service pack is applied. If you find any critical issues after applying the update or service pack, based on emergency change criteria, an emergency Change Advisory Board review will be required.

System Monitoring Policy If your custom solution contains the ability to report errors or problems in the event log, Microsoft can configure Microsoft Operations Manager or Microsoft System Center Operations Manager to use alerts to record and respond accordingly to these events. This configuration occurs during the same change window as the deployment. If the custom solution has no ability to write to the event log, this step is skipped. However, it’s critical that your custom solution provide some way to monitor its health. Without one, Microsoft can’t assess or measure the health of your custom solution and is dependent on users to report problems with solution. If your custom solution can’t be monitored, Microsoft might deem it unsupportable. Custom solutions should be designed to write errors to the event log only when corresponding action is required from Microsoft. All other errors, such as those that contain only events that do not require any corresponding actions from Microsoft, must be written to the Unified Logging Service (ULS) log whenever possible. Microsoft requires that all your custom solutions implement logging according to the policies defined in Event Logging. If Microsoft finds that your custom solution feature is adversely impacting a core service or service stability, Microsoft reserves the right to disable your custom solution. In such a case, Microsoft notifies you immediately after stability has been achieved or the core service is back online. To minimize the impact on users if Microsoft must disable your custom solution, you must code any custom solutions that are interdependent or that depend on external resources to fail gracefully.

Important: Microsoft reserves the right to reject a custom solution that does not implement the appropriate instrumentation. Microsoft Responsibilities  Evaluate whether the appropriate logging information is provided in your custom solution deployment package, and determine whether monitoring is possible and necessary.  If your custom solution adversely affects a core service or service stability in general, disable the solution and notify you. Customer Responsibilities  Ensure that your custom solution writes information to the event log only when the errors require corresponding actions from Microsoft.

 Ensure that your custom solution writes all other information to the ULS log, to assist with assessing the health of your solution.

Log Request Policy Due to confidentiality concerns, Microsoft doesn’t provide any of the following logs to customers:  ULS  Internet Information Services (IIS)  Application  Security  System If you have an issue affecting your deployment environment that might require examination of such logs, SharePoint Online provides assistance when you:  Submit an SR for the issue.  Provide detailed steps so that Microsoft can reproduce the issue. Microsoft then makes use of the appropriate log information to resolve the issue.

Event Logging All of your custom solutions must include and use a customer-specific event source in the event log, in the format . For more information, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). In the Monitoring section of the MSODeploymentGuide, you must provide instructions for actions that must be taken in the event of one or more errors. It’s critical that you’re proactive in monitoring your operations, and any errors related to custom solutions that need to be monitored must be logged in the event log. Third-party solutions can log on to the application event logs, but must have unique IDs, and must specify the source, category, type, and description of the event.

Important: The error strings must fully describe the error that occurred. In addition, each event must have a troubleshooting article associated with it, written using the SharePoint Online Monitoring Troubleshooting template.

Custom Policies and Process Appendix Topic Last Modified: 2015-03-09

Appendix A: SharePoint Online Policies for Sandboxed Solutions

You can customize your SharePoint Online environment more easily and rapidly by deploying partially trusted code or using third-party solutions. Partially trusted code is not subject to the review and process, unlike fully trusted code. In Microsoft SharePoint 2010, sandboxed solutions can be used to accomplish this while still maintaining the security and stability of the SharePoint Online service. For more information about building sandboxed solutions and using third-party solutions, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). Microsoft monitors the resource usage and impact on performance of these kinds of solutions by using various measurements, such as:  CPU execution time  Memory consumption  Unhandled exceptions These measurements are weighted and combined into a single measurement named resource points. Site collection administrators can also use the Solutions Gallery to monitor current resource usage of sandboxed solutions that have been deployed, as described in this excerpt in the TechNet Library. If you use sandboxed solutions, you must adhere to the following policies for their use in your SharePoint Online environment:  Performance degradation resulting from the use of sandboxed solutions in your SharePoint Online environment will not count against the uptime metric specified by Microsoft in your service-level agreement (SLA).

 You’re responsible for fixing any issues that are uncovered in sandboxed solutions that you have deployed to site collections in the SharePoint Online environment.  If the sandboxed solutions that are deployed to a site collection exceed set limits for resource point usage, all sandboxed solutions on the site collection are temporarily disabled for 24 hours.  If you use a Service Request (SR) to request that the sandboxed solutions for a site collection be temporarily disabled, Microsoft will identify which resource quota was exceeded. However, no logs will be provided. Site collection administrators have the authority to install sandboxed solutions to their site collection. However, you also have the option to submit a Configuration Request (CR) to block sandboxed solutions from all of the web applications.

Appendix B: Code Development and Deployment Responsibilities

Designing and building secure applications is a collaborative effort involving multiple roles. The RACI chart in the following table shows Microsoft and customer responsibilities for deploying custom solutions to your SharePoint Online environment. RACI is an acronym for the following:  Responsible (the role responsible for performing the task)  Accountable (the role with overall responsibility for the task)  Consulted (people who provide input to help perform the task)  Informed (people with a vested interest who should be kept informed)

RACI Chart for Custom Solution Development and Deployment

Task Customer SharePoint Online SharePoint Online Operations Engineering Project Initiate and plan RA Management project Project Gather RA Management requirements Development Prepare SharePoint RA I I Online HLD document Development Review HLD C RA document Development Build custom RA solution packages Development Perform developer RA and user acceptance testing Development Package custom RA solutions Development Run MSOCAF RA I

Task Customer SharePoint Online SharePoint Online Operations Engineering Development Write RA I documentation (deployment, rollback, test, event log, client troubleshooting, third-party licensing, security and compliance, monitoring, MSOCAF report, and dependencies) Development Review I RA documentation Deployment Validate custom I RA solution Deployment Deploy production CI RA build Deployment Test post- RA I deployment System Provide monitoring RA I I Monitoring hooks in code System Monitor code with RA Monitoring Microsoft System Center Operations Manager

Task Customer SharePoint Online SharePoint Online Operations Engineering Patching Test patching I I RA against SharePoint Online environment Patching Deploy to PPE I RA Patching Test updates RA I against custom solutions Patching Deploy updates to I RA production Break-Fix Author fix/change RA I C Remediation to custom solution Break-Fix Review and test I RA Remediation changes Break-Fix Deploy changes to I RA Remediation production environment Upgrade Upgrade PPE I RA Upgrade Validate custom RA I solution in a timely manner Upgrade Author fix/change RA CI to custom solution Upgrade Review and test I RA changes

Task Customer SharePoint Online SharePoint Online Operations Engineering Upgrade Upgrade I RA production environment and deploy changes

Appendix C: Escalating Custom Solution Post- Deployment Issues

After Microsoft completes your custom solution deployment, Microsoft sends an email to your designated distribution list about the successful deployment. The following table outlines the steps required to escalate an issue after your custom solution has been deployed. Escalation Process for Custom Solution Issue

Escalation Event How Communicated Responsibility

Escalation Event How Communicated Responsibility 1. Customer identifies issues with After internal triage, the Customer deployed custom solution in customer opens a Service either the PPE or the production Request (SR) to the Office 365 environment. support service desk ([email protected]) by providing a completed escalation template and the severity level. Note: For information about the detailed escalation process, see the Office 365 Customer Operations Handbook.

2. Office 365 support team The Office 365 support team Office 365 support team triages the submitted SR and communicates the status of the evaluates the incident based on SR based on the severity level the severity level. assigned. Severity A issues are Note: communicated over a phone bridge. Severity B, C and D issues For information about are communicated via email. the severity levels assigned to SRs, see the Office 365 Customer Operations Handbook.

Escalation Event How Communicated Responsibility 3. If, after completion of triage Severity A issues are Office 365 support team and using the regular SR process, communicated over a phone customer Microsoft determines that the bridge. Severity B, C and D issues customer issue is due to the are communicated via email. deployed custom solution or Important: configuration, Microsoft follows If the issue is with a the rollback instructions third-party solution, provided in the deployment Microsoft will provide guide to uninstall the deployed logs to help code or configuration in the PPE troubleshoot the issue. for validation, and then in the But it is the customer’s production environment. responsibility to engage The rollback scheduling is based directly with the ISV to on the assigned severity level of resolve the problem. the incident: Microsoft is not Severity A: Rollback is responsible for initiating performed immediately for the engagement with the custom solution in question. independent software Severity B: Rollback of the vendor (ISV) or taking custom solution can be the lead in resolving scheduled at an agreed-on time problems with third- with the customer, and can be party solutions. done outside a change window with written approval from customer. Note: Standard support process, as with any outage or service degradation incident, applies if root cause analysis indicates that

issue is due to out-of- SharePointthe-box Onlinefunctionality. Custom Solution Resources Legacy Release Office 365 Dedicated & ITAR-support Plans © 2015 Microsoft Corporation. All rights reserved. Page 60 of 222

SharePoint Online Custom Solution Developer's Guide (Dedicated Plans) Topic Last Modified: 2014-03-17

Introduction

This document provides SharePoint Online Dedicated plan customers with guidelines and best practices to help you develop custom solutions that you can deploy to the SharePoint Online environment. The Developer’s Guide includes the following topics:  This introduction supplies the context for creating a custom solution, and reviews new information about this guide and SharePoint Online in general.  PART I: Full Trust Custom Solution Development Process summarizes the development process that you must follow to design, develop, and submit fully trusted code (FTC) to Microsoft for deployment to the SharePoint Online environment. Fully trusted code requires deployment or execution by Microsoft on the hosted servers based on SharePoint 2013. Typically, fully trusted code is based on Microsoft .NET and includes dependent files, but it can also include Windows PowerShell scripts or batch files. This process is described in full detail in Custom Solution Policies and Process (FTC).  PART II: Custom Solution Development Best Practices provides developers with information about best practices for SharePoint development and testing. This part also describes the services, features, and configurations that the SharePoint Online service supports.  Custom Solution Developer's Guide Appendix provides links to content that might be useful to developers of custom code for SharePoint Online, and includes a discussion of recommended guidelines for developers.

Note: For supplemental information about partner access and deployment of claims authentication solutions, see the SharePoint Online Partner Access SDK. Most of the content in this guide describes the best practices for developing custom solutions in the SharePoint Online environment for both Microsoft SharePoint 2010 and SharePoint 2013. However, some content is relevant to only one of those two versions. In these cases, the context indicates which version is being addressed. Although the process in Part I applies only to fully trusted code custom solutions that are deployed by Microsoft, we recommend that you review the guidance and information in Part II if you are developing any type of customization for the SharePoint Online environment. What Custom Solution Developers Should Know Readers of this document should be familiar with professional SharePoint development, and have an understanding of the following technologies:  Microsoft .NET Framework  Microsoft ASP.NET

You must also understand how to create and test scalable SharePoint solutions, and how to plan solutions that are upgradeable. For more information about getting started with SharePoint development, see Appendix A: SharePoint Developer Resources. SharePoint 2013 introduces a new application development model, the Cloud App Model (CAM), which enables developers to build SharePoint applications that do not require full trust code to be run on the server. Starting with SharePoint 2013, CAM is the preferred development model for SharePoint Online Dedicated. You must ensure that custom solutions are tested for performance, scalability, security, and stability before you submit your custom solutions to Microsoft. The SharePoint Online hosted service does not include a hosted development environment that you can use, so it is your responsibility or the responsibility of a designated development team to set up and maintain a development and test environment. To assist you with creating an environment that mimics the production environment, Microsoft provides the SharePoint Online Build Guide (available to current customers only). Updates in This Release Here are the most important changes to this guide and to the custom solution development process:  Guidance on using the new Cloud App Model that is introduced in SharePoint 2013.  Updates to existing extensible features in SharePoint 2013 platform are provided. About MSOCAF Microsoft provides the Microsoft SharePoint Online Code Analysis Framework (MSOCAF) for customers to use when analyzing full trust custom solutions, testing the deployment of the custom solutions, and submitting them for installation in the SharePoint Online environment. This tool is not required for apps that take advantage of the new Cloud App Model. You can obtain MSOCAF from MSOCAF Download Site. For more information about how to use MSOCAF, see MSOCAF Help. MSOCAF uses an extensible framework to run a set of executable rules against a custom solution before you submit the custom solution for approval and deployment into pre-production and production environments. For more in-depth information about how to run MSOCAF to analyze your custom solutions, see Custom Solution Policies and Process (FTC). Here’s what developers need to know:  You must use MSOCAF to validate all custom solutions that are developed for SharePoint Online by you and by independent software vendors (ISVs). Validation includes testing the deployment and rollback of custom solutions in your test environment.  Custom solutions must use solution package (.wsp) files.

 For details about MSOCAF rules, see Appendix D: Rules Enforced by MSOCAF.  In addition to validating your custom solutions with MSOCAF, you must conduct additional manual test cases, which you collect in the Custom Solution Test Cases document (available to current customers only, on the Customer Extranet site). You must run your custom solutions through these manual tests in your test environment prior to submission.

PART I: Full Trust Custom Solution Development Process Topic Last Modified: 2015-03-09

PART I: Full Trust Custom Solution Development Process

Note: The information in this section does not apply to the SharePoint 2013 Cloud App Model.

When you introduce custom code to the SharePoint Online production environment, or revise existing code, your development team must follow the process described in the Custom Solution Policies and Process (FTC) document. The process includes these steps: 1. Gather requirements. 2. Create high-level design (HLD) document. 3. Microsoft reviews HLD. 4. Develop custom solution. 5. Test, package, and validate with MSOCAF. 6. Microsoft reviews, validates, and deploys your custom solution.

Important: Don’t proceed with any custom solution development work before Microsoft approves the HLD document. If you proceed with coding the custom solution, but the design is rejected, it could lead to time lost in the overall development cycle and potentially a delay in deployment of the custom solution. If the custom solution plan includes third-party components that bayou will

purchase as part of the custom solution, we recommend that you purchase these components after the HLD is reviewed. For information and resources about SharePoint development, see Appendix A: SharePoint Developer Resources in this document. Solution Files Microsoft requires that solutions that you develop use solution packages that have a .wsp file extension when you deploy custom solutions to the SharePoint Online environment. A custom solution sometimes requires numerous solution packages. Your solution packages can be built in the Visual Studio development system or you can build them manually. Solution files with a .wsp file extension are in CAB-based format, which contains a directory structure and definition files that are understood by the SharePoint deployment infrastructure. SharePoint 2013 imports the solution into the SharePoint store, and then deploys it to the farm. In addition to the directory and definition files, a solution file also contains a set of SharePoint Features, which are logical units of functionality that are self-contained. All configuration files within the solution packages should be pre-populated with production environment values to avoid deployment errors. If you design a solution that requires more than 10 .wsp files, you should reconsider its architecture. It is difficult to manage and deploy that many .wsp files within a single deployment window, and the solution risks rejection due to its complexity. If a solution developed by an ISV does not use solution packages, it can still be submitted to the SharePoint Online operations team for review. However, all custom solutions that are developed by your in-house development team must be packaged in .wsp files. For more information about solution packaging and files, see Building Block: Solutions in the MSDN Library. Analysis of Third-Party Solutions For ISV custom solutions that use Windows Installer (.msi) files, the .wsp files contained in the .msi file must be submitted separately from the .msi file, so the .wsp file can be successfully analyzed. Required Directory Structure and Components in the Deployment Package The required directory structure for the custom solution deployment package consists of a root directory named for the solution being submitted, and the following subdirectories:

 \Solutions artifacts  \Release documents  \Source code  \Installation scripts  \Test documents

See Table 1 for descriptions of the required directory structure for the custom solution deployment package. When you are building the deployment package, refer to the checklist in Appendix C: Custom Solution Deployment Package Checklist.

Table 1. Custom Solution Directory Structure and Package Components

Root Directory and Package Components Description Subdirectories Root Directory Contains the subdirectories that contain the custom solution components. Name this directory for the solution being submitted. \Solutions artifacts Contains the solution packages, including the final tested code. This folder must contain at least one .wsp file. MSOCAF uses this directory to create a CAB file, which is placed in the root directory. (For ISV custom solutions that use .msi files, the .wsp files contained in the .msi file must be submitted separately from the .msi file.) Solution packages Include the final versions of all the solution packages, including final tested code. The MSOCAF report is automatically added to this folder by MSOCAF.

Root Directory and Package Components Description Subdirectories Deployment manifest You must create an XML manifest file to use the Test Deployment and Rollback features in MSOCAF when you deploy your custom solution to your test environment. This file must have the file name DeploymentManifest.xml. Public debug symbols To help in any possible troubleshooting scenarios, include the public debug symbols for all custom code. This symbol file is automatically created by Visual Studio as long as either pdb only or full is selected from the Debug Info setting, which you can access via the Advanced settings on the Build page in Visual Studio. \Release documents Contains all the relevant documents related to the release. This folder must contain at least one .doc or .docx file.

Root Directory and Package Components Description Subdirectories Deployment guide Create a comprehensive set of instructions for deploying the custom solution, following the most current deployment guide template provided by Microsoft. The guide can include third-party licensing information, monitoring information, and scheduling information. Third-party licensing document If you are using a third-party component or solution, provide the licensing details and any necessary keys or certificates for installation. Note: Remember that licenses are required for the pre- production, primary, and secondary environments.

Root Directory and Package Components Description Subdirectories Scheduling Information Provide the expected date for code-drop submission and deployment. In addition, include the expected duration of down times that might be required for deployment configuration and post-deployment configuration. (Include this information in the deployment guide.) Dependencies list Submit a list of all dependencies for the code. This can include accounts and passwords, web services, databases, other solutions, features, updates, tool sets, and libraries. Rollback plan Provide a rollback plan for any components that will be deployed manually. Include screen shots of how the environment must look after a successful rollback. Support troubleshooting Submit end-user troubleshooting document guidance to Microsoft with one or two test accounts, if appropriate, to diagnose problems that are related to your dependencies. If you provide a user account, it should be set up with low privilege and used for no other purpose.

Root Directory and Package Components Description Subdirectories Monitoring troubleshooting Provide all details related to document monitoring the custom solution, including logging details and documentation about all instrumentation. This list commonly takes the form of a table of error codes, the corresponding severity, and root cause. Include these documents in the Monitoring section in your deployment guide and include additional Monitoring Troubleshooting documents as needed. \Source code Contains the source code.

Root Directory and Package Components Description Subdirectories Source code Include the project files and all source code (validated through MSOCAF and including manual test cases), if developed in house. We treat all source code with the utmost confidentiality. For details about the treatment of customer source code, see the "Pre- Existing Work" section of your organization’s contract. Note: If the solution is a third- party, off-the-shelf application, no source code is required for submission.

\Installation scripts Contains any installation or uninstallation scripts that must be run as part of the deployment. The installation scripts should refer to the appropriate file from the \Solutions artifacts folder for any defined deployment packages. For example: Stsadm.exe -o addsolution -filename ..\Solutions artifacts\xyz.wsp

Root Directory and Package Components Description Subdirectories \Test documents Contains all of the test documentation. Test documents and results For testing and validation purposes, it is extremely important to supply a copy of the manual test cases, test plan, test scenarios, unit test results, and all performance and scale testing that you have performed related to the code (and that is not covered by MSOCAF). This is even more important for all code that has a dependency (web service, data, or system) that cannot be tested during validation by Microsoft. Include details about all elements of the custom solution that your organization wants to deploy, including any third-party components and other solutions that you have purchased.

Updates to an Existing Custom Solution When you update an existing custom solution, the existing documentation must also be updated. If the design has changed and now requires a feature enhancement or other change to functionality, you must first submit a new HLD document. If you are updating existing custom code only to address bugs, and there are no fundamental design changes, no HLD document is necessary and only the documentation in the deployment package must be updated.

In the case of an update, provide the following information in addition to the components detailed in Table 1:  A summary of changes. This must summarize what has changed from the previous version (for example, "Master page layout changed, referenced a new CSS file, and updated the underlying JavaScript.").  The original solution source code. As a part of solution analysis, the new source code is validated against this original source code to ensure that no new changes or code issues were introduced other than the planned change.  Anticipated problems during upgrade. Submit details about any errors, rendering issues, or other problems that might be expected when upgrading the custom solution.  Updated support documentation. Include updates for the end-user troubleshooting guide and other documents. Describe anything that has changed and any new features that could potentially require support or monitoring. Depending on which deployment action you choose when you update a custom solution, you must include documentation for the required steps:  Upgrade steps. The upgrade must include the necessary steps for upgrading the solution. We recommend the upgrade method instead of the reinstall method, because only the upgraded components must be submitted for review, rather than a full deployment package.  Rollback steps. The rollback must include the necessary scripts for restoring the previous version of the solution. If the custom solution stores any configuration data that is not part of the custom solution, the steps must include information abooout how to back up that information.  Reinstall steps. The reinstall requires that you submit a completely new custom solution deployment package for review, and must include the necessary scripts for uninstalling the solution and reinstalling the new version. If the solution is causing issues in the SharePoint Online environment, or if the customer requests a rollback, Microsoft follows these rollback steps to restore the previous version.

Note: Site collection features and site-scoped features cannot be deactivated by the rollback process.

1. Deactivate the features that are scoped for the web application and the farm. 2. Retract and delete the solution.

Important: For custom solutions that contain any configurations, the configurations must be backed up prior to this step, or else they will be lost. 3. Add the previous versions of the solution to the solution store and deploy to the farm. 4. Activate the features that are scoped for the web application and the farm.

Validate and Submit the Deployment Package You must provide a configuration request (CR) when you to submit the custom solution using MSOCAF. Open the CR with your service delivery manager (SDM). You must deliver the custom solution package at least 15 business days before the business day on which you want the solution to be deployed. This ensures that Microsoft can test and validate the solution and perform the deployment in a timely manner in the production environment. It is not necessary to submit your custom solution to Microsoft from the same server on which you performed analysis of the solution. Analysis can be performed on one server and the folder structure copied to a different server for submission, as long as all of the prerequisites for submission detailed in this document are met. Microsoft has a Performance Test Policy for custom solutions (available to current customers only, on the Customer Extranet site). Refer to this policy for information about testing requirements. To validate and submit the custom solution deployment package: 1. Ensure that the root directory for the custom solution deployment package contains all required directories and components (listed in Table 1 earlier in this document). 2. Use MSOCAF to analyze the deployment package. 3. If any errors are reported, fix the errors and then rerun the analysis. 4. Provide the required justifications for any remaining errors that will not be fixed. 5. Use MSOCAF to test the deployment of the custom solution in your test environment, and then to test the rollback.

Note: Any changes made after this testing will require steps 2, 3, and 4 to be repeated before you can proceed to step 6. 6. Use MSOCAF to submit the custom solution deployment package to Microsoft.

7. MSOCAF communicates with a web service hosted by SharePoint Online to facilitate submission of the deployment package. Customer Responsibilities  Adequately test all custom code before submitting it to Microsoft.  Describe, test, and document any requirements concerning performance, scale, and language.  Request that the SDM create a CR, and use the CR number given by the SDM when submitting the custom solution through MSOCAF.

Custom Solution Review and Deployment Microsoft performs the review and deployment steps for the custom solution. For more information about these steps, see Custom Solution Policies and Process (FTC).

Note: When you submit a deployment package, it must contain the required directory structure, all files, and the most current templates as outlined in Required Directory Structure and Components in the Deployment Package in this document, otherwise it is rejected.

As part of the deployment package review, Microsoft reviews the scope of the solution and determines whether it is a small, medium, large, or extra-large custom solution. The size of the custom solution is based on the amount of code and the number of .wsp files included in the custom solution deployment package. For more information about solution packages and .wsp files, see Solution Files in this document. Part of the review includes testing, as described in Microsoft Testing of Custom Solutions. Reasons for Custom Solution Rejection FTC solutions must pass through a review and approval process, which includes submittal of the HLD document and validation using MSOCAF. There are various reasons why custom solution submissions to SharePoint Online can be rejected. Here are some of the most common mistakes that result in rejection. Avoid these mistakes, and your solution is much more likely to be accepted on first submission. For complete information about submitting custom solutions, see Custom Solution Policies and Process (FTC).

Documentation Error

 The name of an artifact in the solution deployment documentation doesn’t match an artifact name in the folders.  Instructions are not included in the relevant document sections, especially for manual installations.

Script Failure in Lab

 Scripts use hard-coded values from the development environment (for example, site collection URL and domain names). Scripts should use values for the production environment, not for the development or pre-production environment.

Missing Deployment Instructions

 No rollback or retraction scripts are included in the submission, or scripts do not meet all rollback or retraction requirements.

Deployment Failure

 The installation sequence is incorrect, such as an attempt to activate a feature before the feature has been created  There are script errors, for example, a feature not deactivated during rollback.  Unsupported commands are used, for example, Microsoft SharePoint 2010 functionality that has been deprecated in SharePoint 2013.

Policy Violation The complete custom solution policies are described in Custom Solution Policies and Process (FTC). Make sure your code does not violate any of the described policies, unless you received an exception when your HLD was reviewed.

PART II: Custom Solution Development Best Practices Topic Last Modified: 2015-03-09

PART II: Best Practices

This section presents recommended guidelines that have been developed by Microsoft for development and performance testing of custom SharePoint solutions. Information about custom solution best practices includes the following:  Development Environments  Using SharePoint Web Services  Using the SharePoint Cloud App Model  Using the SharePoint 2013 Client Object Model  Writing Custom Solutions  Writing Manual Installation Scripts  Recommended Guidelines for Testing  Using Business Connectivity Services  Writing Sandboxed Solutions Development Environments

 Use native SharePoint functionality when possible. You should always evaluate whether native SharePoint functionality can be used instead of writing custom solutions.  Evaluate the use of Cloud App Model. When possible, you should evaluate whether the need for a custom solution can be met by using the new Cloud App Model. The client-side functionalities have been enhanced in SharePoint 2013 to encompass a broad set of APIs.

 Minimize the amount of custom code. The less code you need to write, the smaller the risk that bugs are introduced into the system. Also, if you can quickly fix and reinstall an application, the less downtime your system will experience. Sharing common code reduces the code footprint.  Replicate the SharePoint Online environment. To help you build your local lab and test environments, you can use the SharePoint Online Build Guide with every service release (available to current customers only). This guide describes the build settings and product versions that are used in the SharePoint Online production environment, so that you can mimic these settings in your development and test environments.  Ensure a complete software installation. If your development environment will have everything installed on the same server, see Requirements for Developing SharePoint Solutions.  Use source control and automated build processes. Whether a project includes one or many developers, source control is very important. We recommend Visual Studio Team System 2010 Team Foundation Server for source control and build automation. Having a build automation capability makes it easy to create new environments as needed.  Integrate each developer's environment. Developers work within their own environment and use source control to share and integrate their work. Each developer on a team requires an environment similar to the configuration outlined in the MSDN article Requirements for Developing SharePoint Solutions. A separate integration environment should also be maintained for formal daily builds. With a product like Visual Studio Team Foundation Server, an automated build process can be established where the checked-in code is compiled and deployed (usually scripted) to the central development server. The MSDN article Introduction to Team Development provides useful guidance on team development.  Create logical solution versions. Designate a version for the DLLs and .wsp files in your solution. This is a significant help when determining whether the update of a solution has been successful.  Integrate FxCop into the build process. Because MSOCAF validates solutions using FxCop and other tools, it can be beneficial to integrate these tools as a part of the actual build process. Fixing any issues identified by FxCop earlier in the process is much easier than waiting for MSOCAF to identify them after the custom solution is packaged. For more information, see FAQ: How do I run FxCop during a post-build event? in the Visual Studio Code Analysis team blog.

Note: There are community-based FxCop rules that are specifically designed for SharePoint development. You can add these rules to the base FxCop rules and include them in the build process. For more information, search for the term SharePoint FxCop Rules on the Internet.  Move business logic to separate classes. When you plan the application architecture, it is often beneficial to separate each specific functionality into its own class. This allows for easier reuse and easier testing of the functionality. For example, when you implement a custom solution based on a timer job in SharePoint, we recommend that the actual functionality be implemented in a separate class rather than implementing it directly in the Execute method of the custom timer job class. When the functionality is separated from the SharePoint implementation, it becomes much easier to write test applications (typically console applications) that invoke and test the functionality. After the specific functionality is tested and verified, you can then write and test the code to invoke the functionality from the actual SharePoint custom solution code.  Use unique namespaces for custom solutions. Each feature of a SharePoint custom solution is deployed to the file system on the web front-end (WFE) server, into a folder corresponding to the feature name. To minimize the risk of having two features overwriting each other's files, we recommend that each of the features be named with a unique namespace. For example, instead of calling a feature Contract, call it [Company Name].[ Solution Name].HR.Contract.  Use ADO.NET to connect to databases. Microsoft supports connectivity to databases hosted outside the SharePoint Online data center by using ADO.NET, although service-oriented architecture (web services) is preferred. We recommend that developers consider using a Windows Communication Foundation (WCF) application instead of a SOAP-based service whenever possible. For more information, see the MSDN article Guidelines and Best Practices for creating Windows Communication Foundation applications. When you do use ADO.NET to connect to a database hosted in another data center, make sure to follow the guidelines described in the section on connecting to SQL Azure. These connections are often very latent, and you need to plan for security in making the connection. For information about connecting to custom databases, see Access Custom Database in this document.  Use claims-based authentication and authorization. By using a claims-based approach, it is much easier to perform line-of-business (LOB) integration to systems that are claims-aware. For more information about claims, see A Guide to Claims-Based Identity and Access Control Second Edition — Book Download in the Microsoft Download Center. If you choose to purchase the Partner Access feature, you can also develop SAML claims-based solutions as described in the SharePoint

Online Partner Access SDK. Before you begin, verify that your SharePoint Online farm uses Windows Claims or SAML authentication. A claims-enabled custom solution will not work in a SharePoint farm that uses Windows Classic authentication.  Develop asynchronous code that connects to an Internet address. We have observed slow crawl times for code or components that connect to Internet URLs. Examples are stock feeds, RSS feeds, and JavaScript elements from remote services like Google Analytics. We recommend that you write code using an asynchronous call system such as Asynchronous JavaScript and XML (AJAX) or jQuery.  Ensure that dependencies to external systems are managed correctly. For solutions that have dependencies on external services, such as on-premises web services, you should ensure that the external systems are tested to handle the load and are highly available, and that the solution fails gracefully in the event that the external services are unavailable.

Recommended Guidelines for Increasing SharePoint Site Performance Performance is usually a high priority for any website deployment, including SharePoint deployments. One of the bottlenecks to performance is often data retrieval, especially in navigation components. Therefore it is important to make sure that all navigation code is optimal. For more information about how to write well-performing code in SharePoint 2010, see Writing Efficient Code in SharePoint Server in the MSDN Library. Also make sure that proper caching is used to improve site performance as described in Object Caching Techniques in the MSDN Library.

Note: Configure your custom solutions with the appropriate caching mechanisms. For example, the home pages of any portals or other frequently read sites must be configured to use output caching. The output caching feature can be used on a site (or site collection) only if the SharePoint Server Publishing feature is activated for the site. For more information, see Plan for Caching and Performance in SharePoint Server 2013.  Scope Content by Query Web Parts properly. Ensure that all Content by Query Web Parts are scoped properly. For example, if you must retrieve information from just one site, or from one list in a site collection, it uses fewer resources to configure the Web Part to read only that site or list. You should archive any content that is not necessary and that could be inadvertently considered in the

scope of the Content by Query Web Part. Finally, ensure that the numbers of items in the lists that are being queried by the Content by Query Web Part do not grow too large, because this can also cause performance issues.  Use indexes on lists that are data sources. You can substantially improve query performance by ensuring that at least one column in a view is indexed. In addition, if you are sorting or filtering in your view, you should use an indexed column. Using indexed columns in your views also helps to ensure that your queries do not trigger large list throttling in SharePoint 2013. For example, unexpected throttling may occur when retrieving fewer than 5,000 items if the list has more than 5,000 items, and if you are sorting on a non-indexed column. For more information about designing and working with large lists, see SharePoint Server 2010 performance and capacity test results and recommendations in the Microsoft Download Center, and then download DesigningLargeListsMaximizingListPerformance.docx.  Avoid cross-site rollups. We strongly recommend avoiding cross-site queries. SharePoint caching does not support rolling up of content from multiple site collections. This includes the out-of-the- box Content Based Query Web Part. If you must use cross-site queries, follow the guidance in Search Aggregated View in the MSDN Library. For more information about cross-site aggregation, see Aggregating Content in this document.  Use client-side query mechanisms. For a better user experience, create components that run queries asynchronously from the client browser. This allows pages to load faster, so users can see some page content while other data is being retrieved. It can also reduce queuing on the SharePoint web front ends, which improves the overall experience for all users. SharePoint 2010 has very good support for this type of implementation, with features like a client-side object model, REST-based data access, numerous web service interfaces, and client query libraries like jQuery.  Use the Silverlight Web Part for Silverlight applications. SharePoint 2013 includes a Silverlight Web Part, which supports the hosting of custom Silverlight applications. The Silverlight Web Part reads the actual Silverlight application from a Silverlight application (XAP) file. This XAP file can be stored in a document library in SharePoint, or it can be packaged as a solution file and submitted to Microsoft for deployment to the _layouts folder. The Silverlight application can then use the SharePoint client object model or web services to access and manipulate objects in SharePoint 2013.

Using SharePoint Web Services Table 2 specifies whether the web services in SharePoint Foundation 2010 are supported by SharePoint Online, and therefore can be used in custom solutions. Similarly, Table 3 specifies whether the web services in SharePoint Server 2013 are supported by SharePoint Online.

Note: Whenever calls are made to these web services, the calls must be instrumented by using either SPMonitoredScope or SPDiagnosticsService. For more information, see Using SPMonitoredScope and SPDiagnosticsService class in the MSDN Library.

Table 2. SharePoint Online Web Services

Web Service Supported Description Admin web service No Provides methods for managing a deployment of SharePoint Foundation, such as for creating or deleting sites. Alerts web service Yes Provides methods for working with alerts for list items in a SharePoint Foundation site. Authentication web service No Provides classes for logging on to a SharePoint Foundation site that is using forms-based authentication. CellStorage web service Yes Enables client computers to synchronize changes made to shared files that are stored on a server.

Web Service Supported Description Copy web service Yes Provides methods for copying items between locations in SharePoint Foundation. Diagnostics web service Yes Enables client computers to submit diagnostic reports that describe application errors that occur on the client. DspSts web service Yes Provides a method for performing queries against lists in SharePoint Foundation. DWS web service Yes Provides methods for managing Document Workspace sites and the data they contain. Forms web service Yes Provides methods for returning forms used in the user interface when working with the contents of a list. Imaging web service Yes Provides methods for creating and managing picture libraries. Lists web service Yes Provides methods for working with lists and list data. Meetings web service Yes Provides methods for creating and managing Meeting Workspace sites. People web service Yes Provides methods for working with security groups. Permissions web service Yes Provides methods for working with the permissions for a site or list.

Web Service Supported Description SharedAccess web service Yes Provides a method that determines whether a document is being co-authored. Sharepointemalws web service Yes Provides methods that return metadata or list data from sites or lists in SharePoint Foundation. Sites web service Yes Provides methods for working with websites. Spsearch web service Yes Provides methods for remotely performing searches within a SharePoint Foundation deployment. Users and Groups web service Yes Provides methods for working with users and groups. Versions web service Yes Provides methods for managing file versions. Views web service Yes Provides methods for working with list views. Web Part Pages web service Yes Provides methods for sending and retrieving Web Part information to and from web services. Webs web service Yes Provides methods for working with websites and content types.

Table 3. SharePoint Server 2013 Web Services

Web Service Supported Description

Web Service Supported Description OrganizationProfileService Yes Provides an interface for remote web service clients to read and create organization profiles. PublishedLinksService web Yes Provides a published links service interface for remote clients to read and create published links. Search web service Yes Provides methods that can be used to remotely query SharePoint Server search. Social Data web service Yes Provides an interface for remote clients to read, create, and manipulate social data. UserProfileChangeService web Yes Provides a user profile interface service for remote clients to read and create user profiles. UserProfileService web service Yes Provides a user profile interface for remote clients to read and create user profiles.

Using the SharePoint Cloud App Model SharePoint 2013 introduces a new application development model that enables developers to build SharePoint applications that do not require full trust code to be run on the server. Starting with SharePoint 2013, the Cloud App Model is the preferred development model for SharePoint Online Dedicated. The Cloud App Model supports three different hosting options:  SharePoint-Hosted: The entire app lives in SharePoint. HTML and JavaScript may be used, but no full trust code is allowed.  Autohosted: The portion of the app that contains full trust code is hosted in Azure and optionally SQL Azure. These Azure components are provisioned invisibly and multitenancy is managed

automatically. This hosting option is not available in SharePoint Online Dedicated, or on-premises environments.  Provider-Hosted: Similar to Autohosted in that any full trust code is hosted outside of SharePoint. However, the hosting of that full trust code is left completely up to the developer. This code can be hosted on an on-premises web server, or any other 3rd party hosting or cloud service. If supported, SharePoint Online Dedicated will provide guidance on configuring this hosted option.

Note: It’s important to note that the Autohosted option listed above is not supported by SharePoint Online Dedicated. You must use either the SharePoint-Hosted or Provider-Hosted models. The Provider-Hosted model also requires a trust relationship to be setup between SharePoint Online Dedicated and the customer provided endpoint that hosts the full trust code.

For additional details, see Get started developing apps for SharePoint in the MSDN library. Using the SharePoint 2013 Client Object Model SharePoint Foundation 2013 provides a variety of options for building and integrating applications and LOB systems with SharePoint technology using client-side object models. These options promote easy access to SharePoint functionality from remote clients. We strongly urge that, whenever possible, you employ client-side object models for your solution. This will allow you to bypass the custom solution review process and streamline deployment of the solution. The client object model provides simple ways to add, read, update, and manage information that is stored in SharePoint. The primary goal of the client object model is to provide consistent and efficient APIs for manipulating SharePoint objects remotely. The client object model supports three programming models: JavaScript, .NET managed, and Silverlight. Client object model applications can also use the built-in support for Windows Communication Foundation (WCF) services and Representational State Transfer (REST) interfaces, in addition to using the legacy ASP.NET web services. For more information, see Choose the right API set in SharePoint 2013 in the MSDN Library. Writing Custom Solutions Custom solutions, or “farm solutions,” are full-trust code that is deployed to the SharePoint Online environment by Microsoft. To ensure proper integration and support, refer to the guidelines described in Table 4. It is not a comprehensive list of the guidelines for custom solution development, so if a topic is omitted do not assume that it is allowed. For more detailed information about specific types of custom solutions, see the following sections:  General Guidelines for Custom Solutions  Schema-based Development  Branding  Feature Stapling

 Instrumentation  Enable Cross-Domain Access  Audience Targeting  Writing Web Parts  Writing Timer Jobs  Writing Event Receivers  Writing Feature Receivers  Calling Web Services  Configuration Management  Storing Application Configuration  Windows Claims Authentication  Aggregating Content  Upgrading Features in Custom Solutions

Table 4. Recommended Guidelines for SharePoint Custom Solutions

Guideline Description Modular deployable feature solutions To be deployed, custom solutions (including resource files) must be contained within a SharePoint Feature, and packaged as a SharePoint solution package. The SharePoint Feature framework enables you to package sets of interrelated custom solutions as a single Feature, while also permitting inclusion of multiple Features in a solution package. Solution packages are the required form of deployment for custom solutions into the hosted SharePoint Online environment. This is because solution packages can be deployed, upgraded, and removed gracefully. For more information about solution packages, see Solutions Overview in the MSDN Library.

Guideline Description Configure custom solutions for production Configure your custom solutions for the environment production environment, not for the pre- production environment (PPE) or test environment. For example, after the custom solution is turned over to Microsoft, you should not submit requests to edit URLs to change them from the PPE to production environment. Instead, configure your custom solution with URLs appropriate to the production environment. Then include comments in the web.config file where changes need to be made for the PPE, and we will make the appropriate changes. Alternatively, you can include notes in the deployment guide specifying the configuration details that are specific to the PPE environment, and we will make changes accordingly. Do not attempt direct SharePoint database Custom solutions should not directly access access SharePoint Online databases. SharePoint data should only be updated using the SharePoint object model, without attempting direct access to the SQL Server data structures. This protects both the SharePoint Online service during upgrades as well as data integrity.

Guideline Description Use Secure Store Service If your custom solution connects to LOB applications, on-premises databases, or SharePoint Online databases, you can use the Secure Store Service so that user names and passwords are encrypted. However, we do not support the use of Secure Store Service for delegated identity. This means that you can’t use Secure Store Service to pass SharePoint user credentials from the SharePoint farm to an on-premises system. For more information, see Access Custom Database in this document. Referencing SPWeb or SPSite objects In general, when referencing the SPWeb or SPSite objects, you should employ either a "using" statement or an explicit call of the Dispose method to ensure proper use and disposal of the memory objects. For detailed guidance on exceptions to this general rule, see Best Practices: Using Disposable Windows SharePoint Services Objects in the MSDN Library Avoid hard-coding SharePoint artifacts The locations of SharePoint artifacts (like web services, web apps, site quota template names, and lists) should always be configurable values and should not be hard-coded in your custom solutions. This will prevent problems such as features working in the PPE but not working in the production environment or vice versa.

Guideline Description Reduce unnecessary round trips Use caching as appropriate to reduce unnecessary round trips. Improper management of the number of round trips required for interactions with custom solutions can be exacerbated by latency conditions. This results in a poor end-user experience, and could potentially affect back-end service performance. Minimize attack surface Input surfaces in custom solutions must include boundary checks, input data integrity checks, and appropriate exception handling to prevent the potential for cross-site scripting and SQL injection. Specify Code Access Security (CAS) policy and When you package a solution, include a Code safe controls Access Security (CAS) policy for that solution. If necessary, include your assembly in the safe controls list through the solution. With CAS, code is given explicit permissions and can run only under those permissions, regardless of the permissions of the user executing the code. Requiring CAS and registering safe controls allows SharePoint Online to maintain a secure environment while allowing custom solutions. Error handling and logging When you write error-handling code, inherit from the SPException class to ensure that the errors are consistent in appearance with any errors from SharePoint Server. Trap errors at all possible entry points, including constructors. Use logging where appropriate to help troubleshoot errors. Be sure to log all errors on .aspx and Web Part pages to the Unified Logging Service (ULS) log.

Guideline Description Use delegate controls Determine whether the functionality or custom solution you are developing should be written as a Web Part or if it can be written using delegate controls. By using delegate controls, you can easily replace existing controls that are already in the page using less custom code. For more information about delegate controls, see Delegate Control (Control Templatization) in the MSDN Library. XML mapping Use the AppSettings object to implement XML mapping. This can be provided out of the box using the existing Settings framework in .NET Framework 3.5. Avoid creating custom XML files and a strongly typed object for this purpose. Avoid unsafe updates Avoid using AllowUnsafeUpdates. Use ValidateFormDigest() and, if necessary, interact with SharePoint Server objects using elevated privileges. In cases where AllowUnsafeUpdates must be used, set AllowUnsafeUpdates to False in the try-catch finally block, or a Dispose() method as required by the IDisposable interface to avoid security holes. Deployment logging Include detailed messages in the event logs during installation and de-installation to enable appropriate operational troubleshooting. Limit results when querying large lists and For information about limiting results when you updating large lists query and update large lists, see Best Practices: Common Coding Issues When Using the SharePoint Object Model in the MSDN Library.

Guideline Description Provide source code and documentation to Whenever possible, provide source code for third- Microsoft party solutions, along with documentation, to ensure support. Provide licensing disclosure for third-party Full disclosure must be provided to Microsoft for solutions licensed solutions that are to be deployed to the SharePoint Online environment. This must be provided as part of the custom solution deployment package. Include a failover server in web.config All custom database connections should be configured with a failover partner, otherwise, the database will be unavailable in the event of a failover. Syntax:connectionString="Data Source=SERVER_NAME;Failover Partner=SERVER_NAME;Initial Catalog=DATABASE_NAME;Integrated Security=True;Pooling=True"

General Guidelines for Custom Solutions Plan carefully when installing dependencies for your custom solutions, which can have configuration and application dependencies. Dependencies are not always straightforward, nor are they static over the course of development, or even over the life cycle of the code in production. In addition, some dependencies are used by multiple applications. Your development team must do proper planning, especially when there are dependencies between solutions. Limit the number of .wsp files in a custom solution. Large numbers of .wsp files that need to be tracked and managed pose a challenge for deployment. When you have a large number of .wsp files in a custom solution, there is a greater possibility that something will not be installed correctly or the solution will take longer to deploy, and there is a greater chance of mixing incompatible versions of solution packages. We recommend that you scrutinize your deployment plan and keep the number of

solution packages to the minimum number needed for the project. Keep in mind that a solution package can contain several features, so there is no necessity to have one solution package for each feature. Write effective code. Avoid creating unnecessary objects in code. This includes creating SPSite and SPWeb objects as described in these MSDN articles: Optimizing Code Performance and Avoid Unnecessary Construction of SPWeb and SPSite Objects.

Schema-based Development Not all SharePoint artifacts require compiled code. You can create certain types of custom solutions using XML definition files that can be packaged and deployed as .wsp files. These non-code artifacts include:  Site columns  Content types  List definitions  Site templates  Web templates

Note: Organizations can centrally manage content types without having to deploy them to each site collection separately by using the content type hub functionality in SharePoint 2013.

Branding Master pages are a feature of ASP.NET and share common functionality in SharePoint Foundation 2013 and SharePoint Server 2013. Master pages define a predesigned style and layout template for site collections and subsites. SharePoint 2013 provides support for master pages for both content pages and application pages. For information about best practices for modifying master pages on SharePoint 2013, see Web Content Management and Branding in the MSDN Library. Although you can apply master pages manually after site creation, we recommend that you automate this by using feature stapling, as described below.

Feature Stapling Feature stapling is a method by which you can apply or attach a Feature to all new sites that use a given site definition. This preserves the site definition integrity without the complexity and overhead of using code to activate Features. Feature stapling is specifically designed to apply other Features to one or more site definitions, in addition to making those Features available to any new sites created from any site definition. For more information, see Feature Stapling in the MSDN Library.

Instrumentation SharePoint 2013 includes two new classes that can be used for instrumentation purposes.  SPMonitoredScope can be used by custom solutions that run in the HTTP context of SharePoint (Web Parts, Field Controls).  Custom solutions that do not run in the HTTP context (timer jobs, event receivers, and feature activation callouts) should use the SPDiagnosticsService classes to log information in the ULS logs. For more information, see Logging For SharePoint Developers in the MSDN Library.

SPMonitoredScope

By using the SPMonitoredScope class, custom solutions can add information that is shown when using the Developer Dashboard functionality of SharePoint 2013. The Developer Dashboard facilitates the debugging and troubleshooting of issues with page rendering times by providing additional performance and tracing information. For more information, see Using SPMonitoredScope in the MSDN Library.

SPDiagnosticsService

By using the SPDiagnosticsService class, custom solutions can easily write to the ULS log and to the event log. As a general guideline, each custom solution should use SPDiagnosticsService calls before and after time-consuming calls or when calls outside SharePoint Server are made. For more information, see SPDiagnosticsService class in the MSDN Library.

Enable Cross-Domain Access You can enable cross-domain access to SharePoint Online services by using Silverlight. There are two methods you can use:  clientaccesspolicy.xml file  crossdomain.xml file Whichever solution you use, it must be deployed like any other custom solution, by using a .wsp file and following the custom solution deployment process and policies. Do not deploy the .xml file using SharePoint Designer. If you do, the file will not be recognized. The deployment process is described in full detail in Custom Solution Policies and Process (FTC). For information about enabling cross-domain access, see Making a Service Available Across Domain Boundaries in the MSDN Library.

Audience Targeting If you plan to develop a custom solution that uses SharePoint’s audience targeting functionality or the Membership Web Part, a CR might be required to allow you to import Active Directory groups (this

setting is disabled by default). Plan ahead to allow enough time for the CR approval process for your group import request to complete before you deploy your custom solution. For more information about the CR process and timeline, see the SharePoint Online Configuration Request Guidelines, available to customers on the Customer Extranet site. If you enable group import, it will impact the performance of the User Profile Synchronization process. The process may take days, rather than hours, to complete.

Writing Web Parts Web Parts can serve as "building blocks" for custom web applications and pages. Solutions that include Web Parts can be written and deployed by the administrator of a website or by the individual users of the website to provide easy functional customization. Table 5 lists guidelines that are specific to Web Part development. If you have questions about the use of custom Web Parts, contact your SDM. For more information about writing Web Parts, see Building Block: Web Parts in the MSDN Library.

Table 5. Recommended Guidelines for Using Web Parts

Guideline Description Use SharePoint Server architecture The SharePoint Online architecture provides several frameworks for functionality, such as feature deployment. All custom Web Parts should use the SharePoint Server architecture to ensure consistent behavior across the application. Configuration of Web Parts The configuration of the Web Parts that you deploy should allow the flexibility of deploying to the web application level or lower. This improves supportability and maintenance. You are encouraged to include configuration data with the Web Part itself as metadata.

Guideline Description Web Part connections The SharePoint Web Part infrastructure provides a standardized set of connection interfaces that allow Web Parts to exchange information with each other at run time. You should use these when it is necessary to pass data between Web Parts or between a list and a Web Part. There are a number of SharePoint Server filter Web Parts that already emit data. Your Web Part should be able to receive that data if connection with those Web Parts is desired. Separate user interface (UI) and presentation When possible, abstract the presentation layer layer from the code logic by using either user controls (ASCX) or XSL. If the Web Part requires form input, you should utilize user controls, otherwise, the Web Part should output raw XML and apply an XSLT to format the output. When using an XSL, store the XSLT as a Web Part property, allowing for modification from the tool pane. Avoid using a data tables/dataset approach and HTML formatting in the Web Part. Provide source code and documentation to Source code for third-party Web Parts solutions, Microsoft whenever possible, should be provided with good documentation to ensure good support. Provide licensing disclosure for third-party Full disclosure must be provided to Microsoft for Web Parts licensed Web Parts that are to be deployed to the SharePoint Online environment. You provide this information as part of the custom solution deployment package.

Writing Timer Jobs

Timer jobs are a key building block for performing activities in the SharePoint environment. To provide proper monitoring, you should include logging in the Execute method of the timer jobs. In addition, try to separate the business logic for a timer job into a separate class that is invoked by the Execute method of the timer job. For more information, see How to: Run Code on All Web Servers in the MSDN Library.

Writing Event Receivers When you write event receivers that bayou will deploy to SharePoint Online, you must implement tracing calls for each event. Choose your method overloads carefully to ensure that the calling context is the one you expect. For information about best practices for event receiver development, see Best Practices with Event Receivers in the MSDN Library.

Writing Feature Receivers When Feature receivers are used, developers must implement tracing calls for each of the methods that they override.

Calling Web Services Whenever the code in the custom solution calls a web service, implement the proper instrumentation in the custom solution. To aid in troubleshooting, each call to a web service must have a logging call both prior to and after the web service call. This information can be used by the SharePoint Online operations team for troubleshooting purposes.

Configuration Management You can configure SharePoint by modifying the web.config file or through changes to search settings (scopes, managed properties), audience information, and other settings that are typically accessed through the Central Administration page. You must use Feature receivers to implement custom solutions that change the configuration of SharePoint. The Feature receivers can use the appropriate SharePoint APIs to update web.config and the SharePoint settings. Microsoft reserves the right to reject any custom solutions that require manual

configuration of web.config. For more information, see How to: Add and Remove Web.config Settings Programmatically in the MSDN Library.

Storing Application Configuration Applications that must store configuration data (such as URLs or list names) should specify these properties in the section in the feature.xml file. During feature activation, the applications can then read the properties and store them in the hierarchical object store provided by SharePoint or in a SharePoint list. For more information, see Managing Application Configuration in the MSDN Library.

Windows Claims Authentication All new SharePoint Online Dedicated customer farms are now built using Windows Claims authentication. Customer farms that were built prior to SharePoint 2013 version 11.3 can still use Windows Classic authentication for their web applications, but will be migrated to Windows Claims sometime before their upgrade to the next version of SharePoint Online. Depending on the type of customization, it is possible that code that worked prior to the migration to Windows Claims might not work as expected after migration due to changes in the way identity is managed. Although the authentication store is still Active Directory, Windows Classic authentication is different than Windows Claims. It is very important to understand Identity Claim, how it works on Windows Claims, and the impact it can have on custom solutions.

Figure 1. Identity Claim (Windows)

Note: If the claim is encoded, then the casing for encoded claims MUST be lower case and invariant culture, upper case MUST not be used. Characters 1 through 5 (i:0#.w|) are case-sensitive. These restrictions apply only to the encoded claim string. Thus ToUpper corrupts the encoded string and the EnsureUser method breaks with the above error. The output of the claim methods are all in uppercase The typical user value of a Windows Claims authentication logon will look similar to the logon shown in Figure 1 above. It differs substantially from the sAMAccountName you usually get with Windows Classic. This difference will have significant impact on scenarios where custom solutions rely on that value. Here are some of the major scenarios where custom solutions may rely heavily on the user objects:  Any code that uses the following classes:  System.Security.Principal.WindowsPrincipal  System.Security.Principal.WindowsIdentity  System.Security.Principal.NTaccount  System.Security.Principal.SecurityIdentifier  The use of Thread.CurrentPrincipal where the expectation is that a WindowsPrincipal is returned.

 Any hard-coded user or application identities in the code, as well as code that parses or otherwise constructs a user name on the fly. A common example is site provisioning code that provides a user identity for the primary site collection owner.  Outbound WCF calls.  Client-side object model code (that is, Sandboxed solutions) that calls out-of-the-box or custom WCF endpoints.  Code that changes Thread identity or otherwise impersonates a user.  My Site and profile customizations. Consider the simple scenario of programmatically adding a user to an existing group. The easiest way to avoid complications with claims encoding when you construct the user name is to use the SPWeb.EnsureUser method. Otherwise there will be logon issues. This is simpler than the workaround required to get the encoding for an account name. It's also easier, because it’s only necessary to pass in the account name instead of the four parameters normally needed to add a user. EnsureUser automatically takes care of encoding the name and simplifies the code. string login = "Domain\UserName"; string groupName = "Group"; using (SPSite theSite = new SPSite("http://team.contoso.com")) { using (SPWeb theWeb = theSite.OpenWeb()) { SPUser user = theWeb.EnsureUser(login); SPGroup group = theWeb.Groups[groupName]; group.AddUser(user); } }

The same recommendation applies to similar scenarios like these:  Adding a user as site collection administrator.  Adding a user and using SPRoleAssignment to provide access to a site.

There are cases where it might be necessary to pass the encoded claims string as the logon name. If the goal is just to get the encoded claim value for a particular user, then we recommend using SPClaimProviderManager. For example, to get an encoded claims string, you might have to call SPClaimProviderManager.ConvertIdentifierToClaim method:

SPClaim spclaim = ConvertIdentifierToClaim("domain\accountname", SPIdentifierTypes.WindowsSamAccountName); String encodedClaimString = null; if (null != identity) { try { encodedClaimString = claimManager.EncodeClaim(identity); } catch { // just catch any exceptions and handle them appropriately } }

For more information about SPClaimProviderManager, see SPClaimProviderManager members in the MSDN Library. A simple scenario in which you would pass the encoded string is when it is necessary to create a site collection and assign an owner to the site collection. The owner login should be passed as encoded string. For example, here the owner login should have the claims encoded string. Note that the encodedClaimString variable below would be populated with a claims encoded string value through a process similar to the previous example:

SPWebApplication webApp = new SPSite("http://MySiteCollection").WebApplication; SPSiteCollection siteCollections = webApp.Sites; SPSite newSiteCollection = siteCollections.Add("sites/Site_Collection", "encodedClaimString", "Email_Address");

SPSiteCollection.Add method has several overloads. For more information, see SPSiteCollection.Add method in the MSDN Library.

If you are working with the PickerEntity class, the PickerEntity.Key property will be looking for an identifier of a database record. When it assigns a value, the value should be the encoded claim value, as in this example:

PickerEntity pe = new PickerEntity(); SPSecurity.RunWithElevatedPrivileges(delegate() { using (SPSite thisSite = new SPSite(this.Site.ID)) { pe.Key = "ClaimsEncodedStringForDomainUser"; } });

When you work with the client object model, the UserCreationInformation.LoginName property will expect the encoded string. For example, you have to pass the claims encoded user:

ClientContext clientContext = new ClientContext("https://team.contoso.com/"); GroupCollection collGroup = clientContext.Web.SiteGroups; Group oGroup = collGroup.GetById(6); UserCreationInformation userCreationInfo = new UserCreationInformation(); userCreationInfo.Email = "[email protected]"; userCreationInfo.LoginName = "ClaimsEncodedStringForDomainUser"; userCreationInfo.Title = "Admin"; User oUser = oGroup.Users.Add(userCreationInfo); clientContext.ExecuteQuery();

Here are other scenarios where you might need to pass the encoded strings:  When you construct the SPQuery and pass any identity filters.  When you work with the SPUtility class under Microsoft.SharePoint.Utilities namespaces. There are several methods that might not yield correct results if you do not pass the encoded string. For example, when you leverage the SPUtility.GetPrincipalsInGroup to enumerate the principals of the users in a group, you might have to pass the encoded user string for the method. If you do not do so, the method shown below will return a null value:

SPPrincipalInfo[] principals = SPUtility.GetPrincipalsInGroup(temWeb,

"ClaimsEncodedStringForGroup", 100, out reachedMax);

For more information, see SPUtility Members in the MSDN Library. When you work with SharePoint identities in Windows PowerShell, you have to create an SPClaimsPrincipal for the Identity. For example, use the following Windows PowerShell snippet to create a site collection and assign an owner: #Get-SPWebTemplate >$template = Get-SPWebTemplate "STS#0" #Get User Principal >$cp = New-SPClaimsPrincipal -Identity "redmond\SiteOwner" -IdentityType 1 #Create Site Collection >$sp = New-SPSite http://servername:port -OwnerAlias $cp.ToEncodedString() - Template $template

Another common example of code that might work differently in the Windows Claims environment is code that parses a domain-qualified user name and expects to find a backslash separating the domain and user name. The first part of the substring is not going to return the domain name alone, because it contains the claims encoding values with the domain name. SPUser user = GetUser(); //arbitrary method that returns an SPUser string domain = user.LoginName.Substring(0, user.LoginName.IndexOf("\\")); string message = "The domain is: " + domain; //this will display unexpected claims encoding information before the domain info.

Aggregating Content If you want to aggregate content, you can deploy a custom solution that accesses list data and then displays results in either a Web Part or a custom control. Use the techniques in this section to write custom solutions that minimize the impact on performance when they are deployed to the SharePoint Online environment. These types of custom solutions can be designed to aggregate content within a single site collection or across several of them. Data can be accessed for aggregation by using the search interface in the Query Web service, by using the List Web service, by using the REST API, or by using the SharePoint client object model. Among these options, we recommend using the search interface, because it typically has the lowest impact on the production environment, and has better query performance. However, the design of the custom solution should consider the required freshness of the results, because results from a search-based

method of accessing the data are refreshed only after each search crawl (typically once a day). That is usually sufficient to meet most roll-up and reporting requirements. For more information, see List Aggregation Patterns in the MSDN Library.

Accessing Data with Search Using Search Object Model or Query Web Service

The Query Web service exposes the robust search functionalities of SharePoint for both structured and unstructured contents. Custom solution developers can also leverage the search object model to query data against the site collection. Both the Query web service and object model support returning multiple result types.  The Query Web Service is a SOAP-based ASMX web service, and supports a number of operations, including querying and getting search results, getting query suggestions, and getting metadata such as managed properties of a list.  The search object model provides a unified interface for querying against different search providers. It provides a unified interface for searching against different locations and engines. It also allows for combining and merging of results. Using the search object model, you can create custom Web Parts to execute search queries and display the search results returned. You can access the Query Web service reference, where is the SharePoint site from which you want to retrieve the results:  http:// /_vti_bin/search.asmx A custom Web Part can access the Query Web service as follows: 1. Instantiate the web service. 2. Use the credentials of the user running the client application. 3. Execute the QueryEx method, returning the results to a DataSet. 4. Set the DataGridView data source to the first table in the DataSet object, which contains the relevant results. (GetXMLString can be written to collect the data.)

QueryWebServiceProxy.QueryService queryService = new QueryWebServiceProxy.QueryService(); queryService.Credentials = System.Net.CredentialCache.DefaultCredentials; System.Data.DataSet queryResults = queryService.QueryEx(GetXMLString()); resultsGrid.DataSource = queryResults.Tables[0]; StringBuilder xmlString = new StringBuilder(" urn:Microsoft.Search.Response.Document:Document "); xmlString.Append(); xmlString.Append(""); return xmlString.ToString();

Accessing Data with the List Web Service

Through ECMAScript: The ECMA client object model can be used in Web Parts or controls in a page by referencing an ECMAScript (JavaScript) file to asynchronously access the List Web service.  Reference . The file is located in the path Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS  You can also use jQuery with JavaScript by adding a reference to jquery.js file in your custom solution.  To execute any JavaScript function on a page load event, put references to the JavaScript and jQuery files inside the ExecuteOrDelayUntilScriptLoaded function.  The List Web service can be called in your JavaScript code, and you can use the XmlHttpRequest object directly or make use of a JavaScript library that wraps the XmlHttpRequest object.  Make sure that the page is loading the JavaScript library.  When the page is loaded, the SharePoint List Web service must be called. This can be accomplished by making use of the jQuery AJAX method (for example, calling http://yoursite/_vti_bin/lists.asmx). This method can post the necessary SOAP envelope message to the List Web service. The XML of the SOAP envelope can easily be copied from the .NET Web service test form of the desired web method, for example,

http://yoursite/_vti_bin/lists.asmx?op=GetListCollection The code sample below calls the GetListCollection web method when the page is loaded. The complete parameter of the AJAX method is actually a pointer to another JavaScript function that can be called asynchronously when the web service call is done. $(document).ready(function() { var soapEnv = " \ \ \ \ \ "; $.ajax({ url: "http://yoursite/_vti_bin/lists.asmx", type: "POST", dataType: "xml", data: soapEnv, complete: processResult, contentType: "text/xml; charset=\"utf-8\"" }); });

The processResult function is called when the response XML of the web service call is received. In this method a loop is created which will iterate over every List element of the response XML. For every List element a

element is added to the element with the ID attribute set to data. function processResult(xData, status) { $(xData.responseXML).find("List").each(function() { $("#data").append("

" + $(this).attr("Title") + "

"); }); }

Through Silverlight: A Silverlight Web Part or a Silverlight application hosted within a Silverlight Web Part can be designed to asynchronously access the List Web service. You can add a web reference to http://my/sites/your-alias-here/_vti_bin/lists.asmx and create a proxy for the List Web service. ListsSoapClient proxy = new ListsSoapClient(); proxy.GetListItemsCompleted += new EventHandler(proxy_GetListItemsCompleted); XElement Query = new XElement("Query");

XElement viewfield = new XElement("ViewFields"); XElement QueryOptions = new XElement("QueryOptions"); proxy.GetListItemsAsync("MyContacts", null, Query, viewfield, null, QueryOptions, null);

Then the callback method GetListItemsCompletedEventArgs can be used to process list data that is retrieved.

Accessing Data with the REST API

When you use the SharePoint REST API, the service shows SharePoint lists as HTTP resources that can be addressed by a URL. You can append query strings to the URLs in order to specify filter criteria or query logic. The SharePoint REST API is based on the Open Data protocol (OData) for web-based data services, and can return output in the Atom and AtomPub syndication formats (exchanging XML data over HTTP) or in JavaScript Object Notation (JSON) format. The following examples show some URLs that can be used to access the list data through the REST API:  To return the contents of the Parts list in XML format as an Atom feed http://localhost/_vti_bin/listdata.svc/Parts  To return the Parts list item with an ID value of 3 as an Atom feed http://localhost/_vti_bin/listdata.svc/Parts(3)  To return the Parts list as an Atom feed, ordered by the Name field http://localhost/_vti_bin/listdata.svc/Parts?$orderby=Name To improve performance when querying list data for any custom solution deployed to the SharePoint Online environment, use the REST API asynchronously as follows: 1. Create an HTTP request using the POST verb. 2. Use the service URL of the list to which you want to add an entity as the target for the POST. 3. Set the content type to application/json. 4. Serialize the JSON objects that represent your new list items as a string, and add this value to the request body. 5. Use jQuery to access the list data with the REST API: var url = 'http://localhost/sites/sharepointlist/_vti_bin/listdata.svc/InventoryLocations' ; var inventoryLocation = {}; // Insert a new Part location.

inventoryLocation.PartId = $('#hidPartId').val(); inventoryLocation.BinNumber = $('#binText').val(); inventoryLocation.Quantity = $('#quantityText').val(); var body = Sys.Serialization.JavaScriptSerializer.serialize(inventoryLocation); $.ajax({ type: 'POST', url: url, contentType: 'application/json', processData: false, data: body, success: function () { alert('Inventory Location Saved.'); } });

Accessing Data with the Client Object Model

A custom solution can also call the client object model to access the list data. For more information about leveraging the client object model, refer to the TechNet blog article Using the SharePoint Online 2010 Client Object Model.

Displaying Aggregate Data to the User

Regardless of how a custom solution accesses the list data, you can develop an ECMA Web Part, a Silverlight Web Part, a custom Web Part, or even a custom control that will display the data after it has been retrieved from the server. Use an asynchronous technique such as AJAX or jQuery to query and render the aggregated data. This prevents the code that does the aggregated list lookup from blocking the page load.  ECMAScript Web Part. An out-of-the-box ECMAScript Web Part can access data through the ECMA Script object model loaded from the Web Part. You can call the client object model through Java Script to access the list data from SharePoint, or you can use REST API or the List Web service.  Silverlight Web Part. You can design an out-of-the-box Silverlight Web Part to use the List Web service, the REST APIs, or the client object model, or to access the data from lists. It can also be used to host compiled Silverlight application (XAP) files.

 Custom Web Part. Design any custom Web Parts that are used for aggregating content in such a way that they will run on the client and will asynchronously fetch the data from the SharePoint environment.  User control or dialog control within a page. As an alternative to a Web Part, you can also use a user control or dialog box on your page to display the site collection rollup contents that are hosted in an AJAX or Silverlight control. The key to developing such controls is to minimize the number of post-backs and round trips to the server. These controls can cache the data at the client side, which improves the performance by reducing round trips to the server.

Minimizing Load Time

 For ECMAScript. Decide whether to use inline scripts or a different JavaScript file for your application. For a small amount of JavaScript (less than 10 kilobytes) where functions are not reused across controls or Web Parts, it might be preferable to use the inline scripting approach, especially if the JavaScript file will not be cached.  For a Silverlight application. The load time for Silverlight applications corresponds to the size of the XAP file. Although the XAP files can be cached like other web resources, there is still a performance penalty on page load, because the XAP file still has to be parsed.

Improving Performance with Caching

In the case of AJAX clients, maximize browser caching of resources by referencing JavaScript library files in a central location. In addition, you should also use the cache option in jQuery AJAX calls whenever possible: $.ajax({ type: "GET", url: "test.js", Cache = true, dataType: "script" });

Upgrading Features in Custom Solutions SharePoint 2013 provides rich support for Feature upgrading and versioning. You can handle Feature upgrades in two different ways:  Define activities as CustomUpgradeActions in the Feature definition file that gets triggered when a Feature is upgraded.  Implement the FeatureUpgrading events in the Feature receiver.

The Feature definition can also contain information that defines the range of versions to upgrade. This means that developers can choose different upgrade actions for different versions of the solution. For more information, see Feature.xml Changes in the MSDN Library. When you upgrade schema-based artifacts defined by Feature elements, consider whether the Feature has been customized in the content database (for example content type, site column), or whether it is found only in the file system of the web front-end server. This is important, because a non-customized schema-based artifact exists only in the file system of the web front-end server and can thus be more easily upgraded. However, if the Feature is customized or exists in the content database, it cannot be upgraded simply by upgrading the Feature definition file. An example of a Feature that exists in the content database is a custom content type that is associated with a list. Whenever a content type is associated with a list, the schema of the content type is written to the content database. When you upgrade this category of customized Features, you must use the SharePoint object model. Writing Manual Installation Scripts If possible, you should avoid using scripts outside of .wsp files. When you must deploy components manually using scripts (rather than using MSOCAF), follow these best practices:  If you must use scripts outside of .wsp files, try to use only one script. At most, you can use two scripts: one pre-deployment script and one post-deployment script.  Make sure your scripts comply with the deployment feature in MSOCAF to facilitate automated deployment.  Use Pause and Sleep commands in scripts.

Use Pause and Sleep Commands in Scripts The Pause command in the Windows PowerShell command-line interface can be used in an installation script to hold the batch file that is currently running until you press any key. This helps you to verify the output or to wait until the previous command execution has succeeded, in scenarios such as:  Pauses between adding and deploying a solution  Pauses between deploying a solution and any other immediate command  Pauses between retracting and deleting a solution  Pauses between deleting a solution and any other immediate command

 After any command that requires a delay to execute Similarly, the Sleep command in the Windows PowerShell command-line interface allows you to pause Windows PowerShell activity for a specified period of time for such scenarios. Do not use “–ErrorAction SilentlyContinue” or “-EA 0” All scripts that involve enumeration of SharePoint objects must have file-based logging in place to support troubleshooting needs. At a minimum, we require customers to log the start and end timestamp of the script execution and the execution status (Success, Failure). The log file is saved in the current execution directory. Here is a code sample for creating log files and write log entries. $date = Get-Date $outFile = ".\_" + $date.ToFileTime() + ".log"

{ try{ Write-host "Start Execution"; Write("Begin Processing") >> $outFile

#Logic

Write("Status: Success") >> $outFile } catch { write("Error while processing. Message " + $Error[0].Exception) >> $outFile Write("Status: Failed") >> $outFile } finally { Write("End Processing ") >> $outFile Write-host "End Execution"; } }

You get to control what happens when a cmdlet issues a non-terminating error by using the common parameter –ErrorAction(-EA is the alias). Action preference used with -ErrorAction are:  SilentlyContinue: Do not print, continue – Not allowed in MSO scripts.  Continue: Print, continue (this is the default)

 Stop: Halt the command or script  Inquire: Ask the user what to do Make sure that –ErrorAction SilentlyContinue or -EA 0 is not used in your scripts. Use of the SilentlyContinue parameter suppresses any error messages that might occur during script execution. These error messages are never printed on the console and any valid failures are not identified during the script run. If any known issues should be ignored during script execution, ensure tthat he errors to be ignored are properly called out in the script execution instructions in the deployment guide. Recommended Guidelines for Testing The guidelines for the testing process are used and recommended by the SharePoint Online internal development teams, and include the following:  Scope of Testing  Microsoft Testing of Custom Solutions  Logging Requirements for Custom Solutions  SharePoint Online Configuration  SharePoint Online Customization Types  Custom Solutions That Require Database Services  SQL Azure Support in Office 365 Dedicated Plans  Access Custom Database

Scope of Testing

 Do not limit your testing only to what has changed. Regressions in the code can impact seemingly unrelated portions of the custom solution. We recommend full test passes, even for small updates. Ultimately, the extent of testing is up to you.  The secret to success with testing against SharePoint is to adhere to a process and an agile methodology. For guidance on testing concepts and techniques, see Testing SharePoint Solutions in the MSDN Library. For details about our testing policy and your testing responsibilities, see the SharePoint Online Performance Test Policy  (available to current customers only, on the Customer Extranet site).

Microsoft Testing of Custom Solutions When presented with code from customers, Microsoft performs the following tests: 1. Check for memory leaks.  Check for object disposal.  Verify that code does not use Microsoft Win32 APIs (unmanaged code).  Verify that file handles are closed.  Verify that connections are closed.  Run MSOCAF. 2. Determine whether the error handling and exception handling are sufficient.  Verify that all the protected methods can handle exceptions, and that they log exceptions to the ULS log.  Verify that exception handling in the Feature receivers is re-thrown; if not, the Feature is only partially activated.  Verify that proper instrumentation and error handling has been included in the custom solution.  For events that require response from the SharePoint Online operations team, write the event to a customer-specific event source, in the form customer_log, for example contoso_log. This custom event source is created by your development team in the event log. For additional information about event logs, see How to: Create and Remove Custom Event Logs in the MSDN Library.  Verify that any event logs that are generated from in-house or third-party code have unique IDs and include source, category, type, and description. 3. Walk through the code to determine whether all custom solutions fall within the scope of the custom solution policy described in this document. 4. Evaluate whether elevated privileges are needed in all cases where they are requested by the code.  Verify that the relevant SafeControl entries exist in web.config. 5. Evaluate deployment.  Verify that the deployment does not overwrite any system files (pre-existing SharePoint Server 2013 files on the file system).  Verify that the solution can be removed, added to, or upgraded when it is run multiple times.

 Verify that uninstall scripts are provided to roll back to previous version. 6. Verify that the code runs correctly against the current production version of SharePoint. 7. Evaluate the vulnerabilities of cross-site scripting for all data input.  Make sure to use Server.HtmlEncode.  Test using scripts provided at the MSDN reference site Testing Your Web Applications for Cross-Site Scripting Vulnerabilities.  For additional information, see How To: Protect from Injection Attacks in ASP.NET. 8. Test for protection against SQL injection, especially if a custom database is used.  For additional information, see How To: Protect from SQL Injection in ASP.NET. 9. Test for security vulnerabilities. 10. Microsoft Code Analysis Tool .NET (CAT.NET) v1 CTP - 64 bit is a binary code analysis tool that you can use to identify common variants of prevailing vulnerabilities, which can give rise to common attack vectors like cross-site scripting (XSS), SQL injection, and XPath injection. MSOCAF makes use of CAT.NET.

Additional Recommendations

Here are some guidelines that we recommend, but are not a basis for solution rejection:  CSS, JavaScript, images, and styles should be on the hard disk, to use IIS compression (GZip).  Caching should be used appropriately, invalidating the cache as appropriate.  Verify that code is thread safe.  Verify SQL queries for Enterprise Search, as described in this reference article: Best Practices: Writing SQL Syntax Queries for Relevant Results in Enterprise Search

Test Environments

Your testing should take place in a farm environment (with two web front-end servers and separate servers for service applications and content databases) rather than in a standalone environment. Your test environment is different from a development environment and should mimic the SharePoint Online production environment, It should include one or more web applications, a copy of one or more SQL Server content databases, and at least two web front-end servers. To build the test environment, refer

to the SharePoint Online Build Guide (available to current customers only, on the Customer Extranet site). The goal in testing your custom solutions is to find any failure points (see next section) and test them. Speed is not important; in fact, for testing purposes memory should be limited to see what happens. If an application passes in this type of environment, it probably doesn't have large memory requirements.

Failure Points

There are a number of common causes of failure that occur at some time in the life of the solution. The following causes are considered by the SharePoint Online engineering team to be the most common failure points.  Network and infrastructure configuration. The network configuration in the test environment is different from the SharePoint Online production environment. For example, the test configurations do not have correct trusts and forest structure, or the URLs are not configured for Secure Sockets Layer (SSL).  Altered computer configurations. A developer configures his own computer, and writes a solution to mimic those (altered) settings. Then the solution is installed in a clean environment where the developer has access. The failure point comes when the developer "fixes" an issue on his own computer, but the fix can't be duplicated in the clean environment.  Dependencies.For any custom solutions that depend on external resources or on other custom solutions, you must code them to fail gracefully if the resource or solution they depend on is unavailable, to minimize the impact on users.  The human element: variation. There are numerous ways to deploy solutions, but the best course of action is to adhere to a process and deploy the same way every time, which eliminates any human variables as much as possible any human variables. For example, when the same tasks must be assigned to different individuals, failure could result.  The human element: rushing. Simple changes can be more complicated than they look. For example, you might make a very minor change, such as changing the name of a Web Part. However, due to time constraints this "minor text change" is not properly understood by the tester. Consequently, no testing is done, and the installation fails. Why? The developer did remember to change the XML manifest file to point to the new Web Part name, but forgot to change the name in the Feature receiver. That's just one scenario; many similar things could occur.  Solution files are fragile. A change in the code or even a change to the structure of the website can keep a solution from deploying properly. There is no developer tool that can show everything

that the solution is going to do. The only thing you can do is test each change. It can be very difficult to know whether the latest version of the solution is working or not, especially because developers rarely wipe their computers clean after each install. It is really the responsibility of your test teams to verify that the solution works—in an upgrade situation, for a fresh install, or in the production environment as it is configured today.  Multiple web front-end (WFE) servers. The environment hosted by Microsoft contains multiple WFE servers. It is possible that the code or deployment process can fail when multiple WFE servers are in a server farm. Make at least one pass against a farm configuration with two WFE servers during your testing.  Incomplete removal of previous versions. A previous version might not be completely removed from development integration or a test environment, which can cause a number of false positives to be returned. Clean-up prior to the installation of a new build is critical to successful development on SharePoint Online. In addition, a detailed list of steps for a complete retraction is necessary in case there is a failed install or failed smoke test.  Deployment scripts without adequate pauses for longer running operations. The SharePoint Online environment consists of farms with multiple WFE servers. Because of this multiserver environment, it can take a while for timer jobs to complete. Dependent operations like retractions and deletions require a pause between them to allow enough time to validate that the prerequisite operations have completed.  Access design. A solution might not be designed to work correctly in an environment with one-way trusts.  Authentication. A solution might not be designed to work correctly with the authentication method (Windows Claims or SAML claims) that is used on the SharePoint web application.

Required Performance Tests

It is your responsibility to test custom solutions for performance, and to provide the test results to Microsoft as a part of the custom solution deployment package. You must conduct the performance testing according to the guidelines provided in this document. To validate the impact of deploying the custom solution, you must compare a baseline of the performance of the system prior to the deployment of the custom solution with your post-deployment performance. The tests must measure the impact on the SharePoint servers, such as CPU and memory. To do this, collect the performance counters listed in Step 2 below. The tests must also measure the

performance of the page. This can be measured by capturing the time to last byte (TTLB) setting using a web test.

Step 1: Establish a Test Environment

The load testing environment should have the same caching configuration as the SharePoint environment, as described in the build document. This should include the following:  Binary large object (BLOB) caching should be enabled.  If the site has the publishing feature enabled, you should also enable SharePoint Object caching.

Step 2: Establish the Baseline with Initial Testing

Before you test the custom solution, establish a baseline by performing a test before you deploy of the custom solution. This should include the following actions:  Perform an IIS reset.  Warm up the system by accessing and invoking the same functionality that will be tested. The tests should access all the pages and functionality that are impacted by the custom solution prior to actually deploying them. Run these tests using a variety of different user loads. At a minimum, the tests should be performed at a targeted number of requests per second. Capture the following counters on the SharePoint WFE servers:  Processor(_Total) \ percentage of processor time  Process(w3wp) \ percentage of processor time  ASP.NET \ Request Execution Time  ASP.NET Apps v2.0.50727 \ requests per second  Memory \ percentage of usage peak  Memory \ available megabytes  Time to last byte (TTLB) information for each page.

Step 3: Run the Tests with the Custom Solutions

Deploy the custom solutions to the farm and perform the same tests as in step 2 above.

Logging Requirements for Custom Solutions It is critical that each custom solution provide a means of monitoring its health. If your custom solutions can’t be monitored, Microsoft might deem them to be unsupportable. Custom solutions should be designed to write errors to the event log only when action is required from the SharePoint Online operations team. All other errors—those that contain only events that do not require any actions from the SharePoint Online operations team—must be written to the ULS log where possible.

Important: Microsoft reserves the right to reject a custom solution that does not implement the appropriate instrumentation. If we find that a custom solution feature is adversely impacting a core service or service stability, we reserve the right to disable the custom solution. If this happens, Microsoft notifies you immediately after stability has been achieved or the core service is back online. To minimize the impact on users if we must disable a custom solution, you must code any interdependent custom solutions to fail gracefully. Microsoft Responsibilities  Evaluate whether the appropriate logging information is provided in the custom solution deployment package, and determine whether all necessary monitoring is included.  If a custom solution adversely affects a core service or service stability in general, disable the custom solution and notify the customer. Customer Responsibilities  Ensure that the only times that the custom solution writes information to the event log are when the errors require involvement from the SharePoint Online operations team.  Ensure that the custom solution writes all other information to the ULS log, to assist with assessing the health of the custom solution.

The Event Log

If the custom solution contains the ability to write to the event log to report errors or problems, Microsoft might configure Microsoft Operations Manager or Microsoft System Center Operations Manager to record and respond to the events using alerts. This configuration occurs during the same change window as the deployment. However, it is critical that the custom solution provide a means of monitoring its health. Without one, Microsoft is dependent on users reporting problems with the custom solution, and has no means to independently assess or measure the health of the custom solution. All custom solutions from your development team must include and use a customer-specific event source in the event log, in the format customer_log, for example contoso_log. This event source can be created either with a Windows PowerShell script or in the code itself during feature activation. From a Windows PowerShell script: A simple one-time cmdlet to create a new event log (Customer_Log) and new event source (NewApp) can be executed on each web front-end (WFE) and application server in the farm, as described in New-EventLog TechNet article. For example: C:\PS>new-eventlog -source NewApp -logname Customer_Log In custom solution code: Code used in the custom solution to activate the feature can create a new event log (Customer_Log) and new event source (NewApp). For example: if (!System.Diagnostics.EventLog.SourceExists("NewApp")) System.Diagnostics.EventLog.CreateEventSource("NewApp","Customer_Log");

In either case, an event source instance must be created to write to the event log. For example: EventLog eventLog1 = new EventLog(); eventLog1.Log = "Customer_Log"; eventLog1.Source = "NewApp"; eventLog1.WriteEntry("This is a simple event log entry");

For additional information about creating and writing to custom event logs, refer to these articles in the MSDN Library:  How to: Create and Remove Custom Event Logs  How to: Write Entries to Event Logs

Ensure that new entries can be continuously written to the event log by setting OverflowAction to OverwriteOlder. In the Monitoring section of your deployment guide, you can provide instructions for actions that must be taken in the event of a logged error. Proactive operational monitoring is critical, and any custom solution–related errors that will be monitored must be logged in the event log. Third-party solutions can write to the Application event log, but must use unique IDs, and specify the source, category, type, and description of the event.

Important: The error strings that are written to the event log must be adequately descriptive of the error that occurred. Within the custom solution deployment package, the deployment guide must include the following information for all events:  Event type  Event source  Event category  Event ID  Error string  Description of error  Impact of error

In addition, each event must have a troubleshooting article associated with it.

Unified Logging Service

For events logged to the Unified Logging Service (ULS) log, each custom solution must implement a uniquely named categorization using the SPDiagnosticsArea class in SharePoint 2013. This approach allows events from the custom solution to be grouped together or filtered.

SharePoint Online Configuration The ways in which the configuration of the SharePoint Online environment can be changed are defined in Table 6 below. Table 7 shows whether a particular configuration is supported. If a configuration is not listed, please contact your SDM to learn whether it is supported.

Table 6. SharePoint Online Configurations

Configuration Supported Comment Custom-managed path No SharePoint Online does not support custom-managed paths for site collections. SharePoint database schema No Changes made directly to the change database schema are not supportable. SharePoint database data No No direct access is allowed to the access SharePoint databases. All access to the databases is through the object model (OM) or web services.

Configuration Supported Comment Modifying built-in SharePoint No SharePoint Online does not files support any changes to the SharePoint files on the file system. This includes shipped site definitions. Web services access Yes Almost all web services that ship with SharePoint Server are exposed. For more information, see Using SharePoint Web Services in this document. WCF Data Services access Yes All WCF Data Services (formerly known as ADO.NET Data Services) that ship with SharePoint Server are exposed. Silverlight Web Part Yes SharePoint 2013 includes an out- of-the-box Silverlight Web Part. SharePoint Designer editing Yes Any changes that can be made with SharePoint Designer 2013 are supported. However, SharePoint Designer 2010 is not compatible with SharePoint 2013. Changing mapped host name No SharePoint Online does not after deployment support changing the hosted domain name, for example, sharepoint.contoso.com, after the environment has been deployed. You should carefully choose the host name for your environment before service adoption.

Configuration Supported Comment Visual Studio installation on No Microsoft does not allow Visual deployment Studio to be installed on a web front-end (WFE) server for troubleshooting. Installation of Microsoft Office No Microsoft does not allow client on server Microsoft Office clients to be installed on a WFE server. Publishing of service No Microsoft does not publish applications for cross-farm service applications for access access from remote farms. Accessing on-premises service No SharePoint Online does not applications support service application proxies that would connect to on-premises service applications. The one exception to this is the FAST Search Query Search Service Application. Using RBS Providers No Microsoft does not allow a remote BLOB store (RBS) provider to move the storage of large binary data (BLOBs) from SQL Server databases in the SharePoint Online environment to a commodity storage solution.

SharePoint Online Customization Types Table 7 describes the various ways that SharePoint can be customized and whether or not the custom solutions are supported in the SharePoint Online environment. These custom solution types apply to SharePoint 2013. Non-supported types are either planned for a later release of the SharePoint Online

service or have been determined at this time to pose a risk to the environment, add additional operational overhead, or be potentially difficult to upgrade to future versions of SharePoint Online.

Table 7. Support for Custom Solution Types

Customization Type Supported Comment SharePoint Feature Yes A SharePoint Server Feature is a server- side custom solution at the file system level. It can contain modular items that can be installed and activated in a SharePoint Online environment. Feature stapling Yes Feature stapling, also known as Feature site template associations, is the ability for a Feature to be attached to all new instances of sites that use a given site definition, without modifying the site definition or creating code routines to activate the feature on each site. Feature event receiver Yes A Feature event receiver, or Feature receiver, is a server-side code routine that is called as part of certain key events in the lifetime of a Feature, such as installation, activation, deactivation, or removal.

Customization Type Supported Comment Web application No A web application is code or content installed in a new web application directory, or as a subdirectory under an existing web application. It provides functionality that SharePoint technology does not. Supporting additional web applications poses a burden on the SharePoint Online operations team. Web service Yes A web service is server-side code that exposes code routines that are called from remote systems. The web service must be hosted in one of the deployed web applications. Windows Server service No The Windows Server service is installed on the server to perform major actions. It runs in a separate process space from the SharePoint Server instance. A service has a relatively high cost for deployment and manageability. SharePoint timer job Yes A timer job is a built-in type of SharePoint Server object that can perform various tasks within the SharePoint Online environment. Timer jobs run on a scheduled or one-time event basis.

Customization Type Supported Comment Scheduled task No A scheduled task allows code to run on the Windows-based server on a defined schedule. When the event occurs, the code is run. There is no trigger from SharePoint Server. Scheduled tasks are not supported, because they run outside of SharePoint Server. Web Part Yes A Web Part is a modular component that is used within the SharePoint environment to perform activities or display information. Event handler Yes An event handler is a feature scoped for web applications that contains server-side code routines. It is called when registered events occur in the SharePoint environment. Custom event handlers can be attached to site collections, sites, lists, or document libraries. Backward-compatible event No A backward-compatible event handler handler is a server-side code routine that is called when a registered event occurs within a SharePoint Server document library. Backward-compatible event handlers can only be attached to and have a scope of a document library.

Customization Type Supported Comment Custom site definition No A site definition is a server-side collection of files that defines the structure of one or more site templates. When a site is created with a custom site definition, it is dependent on that site definition in the future, including when upgrading to a new version of SharePoint Server. Site template Yes A site template is a package that contains a customized site design based on an existing site definition. This package is typically created by using the Save Site As Template functionality. Web template Yes A web template is similar to a site template, but it is typically created by developers. A web template persists in the SharePoint database as a solution file, with a .wsp extension. The template is stored in the Solutions gallery of the site collection. A web template can also be deployed as a sandboxed solution. For more information about web templates, see:  Web Templates  SharePoint 2010 and web templates List definition Yes A list definition provides the schema for a SharePoint Server list.

Customization Type Supported Comment List template Yes A list template is a package that contains a set of custom solutions from a base list structure. A list template should not be confused with a list definition. Field type Yes A field type is an extensible method for allowing new common data structures in SharePoint Server for use in lists or other locations that can use SPField objects. Master page Yes A master page defines the layout, fonts, and formatting for the pages that are associated with it. Application Master Page Yes An application master page defines the layout, fonts, and formatting for the administration pages that are associated with it. Page layouts Yes A page layout is a page template that controls how the page looks and exactly which elements (such as lists and libraries) should be present on the page. The publishing page layout can be attached to a master page that defines its layout and formatting. Custom application page Yes Custom application page mapping mapping allows for substitution of specific application pages used by SharePoint. For more information, see SPWebApplication.UpdateMappedPage method in the MSDN Library.

Customization Type Supported Comment _layouts page Yes An _layouts page is any page stored in the _layouts virtual directory in SharePoint Server. Custom CSS file Yes A Cascading Style Sheet (CSS) file is used to format the contents of web pages. It contains style rules that define how to display HTML elements. SharePoint theme Yes A SharePoint Server theme is a collection of graphics and cascading style sheets that can modify how a website looks. When you use a SharePoint theme, add a manual rule to ensure that all solutions are only targeted for O15 site collections. Content type Yes A content type is a reusable collection of settings that can be applied to a certain category of content. Content types enable the management of metadata and behaviors of a document, item, or folder type in a centralized, reusable way. Column template (column Yes A site column, also known as a field, is definition) a reusable column definition, or template, that can be assigned to multiple lists across multiple SharePoint sites. Site columns decrease duplication of work and help ensure consistency of metadata across sites and lists.

Customization Type Supported Comment Delegate control Yes A delegate control allows certain predefined elements of the SharePoint environment to be replaced (like a field control) by other controls through SharePoint Features. Form template Yes A form template is a control template based on user-controls (ASCX-based) that brings together multiple controls into a nested structure, where each control consists of templates and can be used to richly extend list item forms. Custom action Yes A custom action is an item (command) that is added to the user interface. Coded workflow Yes A coded workflow is a Windows Workflow Foundation workflow that references an assembly for the workflow pipeline. No-code workflow Yes A no-code workflow, also known as a (declarative workflow) declarative workflow, is a sequential workflow pipeline that is configured on a list or document library. It requires no installation of server-side code. Workflow activity Yes A workflow activity is a compiled class that is used as a part of the modular steps in a Windows Azure Workflow. An activity is used as part of a Windows Azure Workflow action that will be run. Windows Azure Workflow activities run as server-side code when used as activities in the SharePoint environment.

Customization Type Supported Comment Workflow condition Yes A workflow condition is a compiled class that is used as a part of the modular steps in a workflow. A condition is used to determine when a workflow action will be run. Workflow conditions run as server-side code when used as conditions in the SharePoint environment. Solutions that customize or No Central Administration (CA) is currently change the Central not provisioned on all farm WFE Administration web servers as a best practice. In the event application that a custom solution is deployed to CA, it is deployed only to the computers where CA is provisioned. This results in a situation where, if there is the need to provision a new CA on a different server on the farm, the custom solution is not deployed to the new server. This causes the features using the solution to malfunction. Document icon Yes A document icon is a graphical item that is used to represent corresponding documents that are exposed within document libraries. Each preconfigured document type in SharePoint has a corresponding document icon entry in a server configuration file, but other file formats might lack appropriate icons. Document icons can only be modified by submitting a CR through your SDM.

Customization Type Supported Comment iFilter or Connector Yes An iFilter is a server-side component (protocol handler) that is used by the indexing system to index documents that are identified as having a file format that is associated with the iFilter. Custom iFilters require deployment to all servers in the environment that do indexing. They also require changes to mapped properties for search. In previous SharePoint products connectors were known as protocol handlers. A connector enables indexing applications like SharePoint Server to systematically crawl the nodes of a data store to extract relevant information to include in the index. Each connector is used to index a specific type of data store. For a list of default connectors, see Default connectors in SharePoint Server 2013. Document converter No A document converter is a custom executable file that takes a document of one file type, and generates a copy of that file in another file type.

Customization Type Supported Comment Information management Yes An information management policy is a policy set of rules for a certain type of important content. A policy allows administrators to control and evaluate who can access the information, how long to retain information, and how effectively people are complying with the policy itself. External content types Yes (unless a new single sign- External content types are reusable on account is required) metadata descriptions of connectivity information and data definitions, as well as the behaviors you want to apply to a certain category of external data in your SharePoint 2013 environment. Excel user-defined function Yes A user-defined function (UDF) is server- (UDF) side managed code, run by Microsoft Excel Calculation Services to provide capabilities that are not included in the base product. These include:  Functions that are not built into Excel.  Custom implementations to built- in functions.  Custom data feeds for legacy or unsupported data sources.  Application-specific data flows.

Customization Type Supported Comment InfoPath Forms Services Yes Custom code for Microsoft InfoPath custom code Forms Services is uploaded and hosted by the server-side InfoPath Forms Services. Note: These InfoPath forms are considered custom solutions and must go through the custom solution submission and validation process. The code-behind .dll must be extracted from the .xsn template file, so it can be successfully analyzed using MSOCAF.

InfoPath form view control Yes An InfoPath form view control is a server-side viewer control for InfoPath Forms Services that can display a web browser view of an InfoPath form. HTTP handler No (only supported if not An HTTP handler is used to handle file used for authentication) requests in the ASP.NET 3.5 framework. For example, in ASP.NET 3.5 and SharePoint Server 2013, ASPX page requests and ASMX web service requests are served by HTTP handlers. HTTP module No An HTTP module is a class that handles runtime events in ASP.NET 3.5 and SharePoint Server 2013.

Customization Type Supported Comment Pluggable authentication No A pluggable authentication provider is provider a module used by ASP.NET 3.5 and SharePoint Server to replace the built- in authentication providers. Custom modules require a high level of testing to help ensure security. Pluggable single sign-on No A pluggable SSO provider is a modular (SSO) provider component that can be used to handle the storage and mapping of credentials for use in connecting with third-party or back-end systems. This custom solution type requires a high level of security review and scrutiny. STSADM command No A custom STSADM command extensions extension is server-side code that allows the Stsadm utility to make new commands available to run from the command line. Console applications No A console application must be run manually by the SharePoint Online operations team. Inline code No Inline code is server-side code that is directly embedded into a web page. Inline code has a high level of risk compared to compiled assemblies.

Customization Type Supported Comment Web.config settings change Yes The web.config file controls most of the settings for the ASP.NET environment that SharePoint Server 2013 is built on. Any modifications to web.config settings must be added or removed using the SPWebApplication class and SPWebConfigModifications property, so that they are applied on all the WFE servers. Manual modification of the web.config settings is not supported. Custom security policy Yes A custom security policy grants code access security (CAS) rights to certain server-side code components that run under a specific web application context. COM server No A component object model (COM) server is an unmanaged library that typically runs on a server with full permissions. COM objects typically perform poorly when interops are set up between the COM object and .NET code. Sandboxed solution Yes A sandboxed solution is a solution file that can be uploaded to individual site collections by site collection administrators. External data lists Yes In SharePoint 2013, the external data list type is used for displaying content that comes from Business Connectivity Services (BCS) Enterprise content types.

Customization Type Supported Comment Silverlight client object Yes The Silverlight client object model is a model customization client-side solution that runs in the browser. SharePoint 2013 provides support for writing these types of customizations. Service application No A service application is a service that can be accessed by multiple web applications. It is managed through the Central Administration site. Excel JavaScript object Yes The Excel JavaScript object model model (JSOM) enables client-side JavaScript scripts to run in the browser and utilize services provided by SharePoint 2013. Ribbon extensions Yes The Ribbon is the new user interface component in SharePoint 2013 that replaces traditional toolbars. Solutions using the dialog Yes SharePoint 2013 provides a new box platform programming interface that uses dialog boxes to show information and interact with the user. Client object model Yes A client object model is a programming interface that can be called from client- side solutions. SharePoint 2013 provides Silverlight, ECMAScript, and Microsoft .NET–managed interfaces. REST Yes A representational state transfer (REST) is a form of interface that can be used from custom applications. User profile exports No SharePoint Online does not support user profile exports.

Customization Type Supported Comment Managed metadata Yes SharePoint 2013 provides a model for centrally managing metadata. Conversion services No SharePoint 2013 provides interfaces for data conversions. Claims provider Yes (claims augmentation A claims provider is a software only) component or service that issues claims and packages claims into security tokens. Your claims provider solution must deploy the assemblies and all of their dependencies to the global assembly cache (GAC) of all server roles, including web front end and application server roles. Failure to do so can result in service outages. For more information about avoiding issues with custom claims providers, see Learning About Claims-Based Authentication in SharePoint 2010 in the MSDN library. Windows PowerShell No (except where MSOCAF SharePoint Online does not support functionality is not supported) running manual Windows PowerShell scripts in the hosted environment.

Custom Solutions That Require Database Services When you develop solutions, you might need to have database services provided for your custom solutions. If a custom solution requires database services, the following options are available:  Host the custom database on premises and access it through Business Connectivity Services (BCS). In this scenario the custom database is hosted on premises in the customer's data center. The custom solution makes use of BCS to connect to and use the database services.

 Host the database solution on the Microsoft SQL Azure technology platform. In this scenario the custom database is hosted on SQL Azure by Microsoft. The custom solution deployed to SharePoint Online connects to the cloud-based databases. For more information, see SQL Azure Support in Office 365 Dedicated Plans in this document.

Note: The SQL Azure services are not a part of the SharePoint Online contract, and must be acquired separately.  Host the custom database in the Microsoft data center. SharePoint Online supports the use of a SQL Server database, following the guidelines described in Table 8. If a database custom solution item is not listed in the table, do not assume that it is therefore allowed. Contact your SDM for further information. SharePoint Online supports only one custom database to be utilized by all custom solutions developed by the customer. One additional custom database is allowed for each approved third-party custom solution that requires a custom database.

Note: Databases that are resource-intensive—that have high storage, CPU, connections, and memory requirements—cannot be hosted. You have the option to host a resource-intensive SQL Server database on your own servers in your own data centers.

Table 8. Custom Database Support Guidelines

Database Custom Solution Supported Comment SQL Server database Yes The Microsoft Online Services infrastructure uses SQL Server hosted on the existing SharePoint Online infrastructure. The current version supported by Microsoft Online Services is Microsoft SQL Server 2008 R2 for SharePoint 2010 farms. Custom non-SQL Server No SharePoint Online does not database support database servers other than SQL Server. You can choose to host such databases on your own premises and integrate them with SharePoint Online using the WCF interface with a web service.

Database Custom Solution Supported Comment More than one custom SQL No (with exception for ISV) SharePoint Online hosts a single Server database SQL Server database for customers on the shared SQL Server infrastructure. If you want to deploy your own custom solutions, you are allowed one custom database for that purpose. One additional custom database is allowed for each approved third-party custom solution that requires a custom database. Direct database access Yes Ensure that proper security measures are in place. Applications that make direct access to on-premises or cloud- based databases using ADO.NET should design for highly latent connections.

Database Custom Solution Supported Comment Custom-developed Web Yes Custom applications must be Parts/SharePoint Online pages isolated from out-of-the-box with custom database features, and should run as an integration independent entity. Failure of the custom database access should not cause the entire farm to fail. No standard existing functionality (for example, Search and workflows) should fail due to a failure on a custom database. AJAX UI implementation is recommended when you connect to a custom databaseso you can minimize page load impact if the custom database connection becomes slow. Custom database as an No A custom database cannot be authentication or credential store used as an authentication store. No credentials are allowed to be stored. Access to SQL Server No Customer access to the SQL Server database using the SQL Server client tools is not permitted under any circumstances, even during troubleshooting. Backups of the custom SQL No Microsoft cannot provide a copy Server database of a customer’s custom SQL Server database.

Database Custom Solution Supported Comment Installation of a copy of a SQL Yes The creation of the custom SQL Server database or creating a Server database in the hosted custom SQL Server database SharePoint Online environment using a script can be done by providing Microsoft with a copy of the SQL Server database (not populated) or through the use of scripting to create the database and associated schema in a Feature receiver. Upgrade path Yes All databases hosted by Microsoft are subject to the same upgrade strategy as the SQL Server product offering. Customers will be notified of plans to upgrade the SQL Server build or version in advance (with six weeks’ notice) of the actual exercise and are responsible for testing that their custom database and the functionality they are using will work with the new build or version. As of the writing of this document, SharePoint Online supports only SQL Server 2008 R2 for SharePoint 2010.

Database Custom Solution Supported Comment SQL Server Reporting Services No The SQL Server team has Web Parts (Restricted to pre-SP2 released Web Parts to display SQL Server 2005 version) data within a Reporting Services system. However, only pre-SP2 versions of SQL Server 2000 and SQL Server 2005 Reporting Services Web Parts can work within a hosted environment. The current design of the Reporting Services Web Parts requires the Reporting Services server to be hosted within the same domain as the SharePoint Online environment. Customers who want to use the shipped Reporting Services Web Parts should know that SharePoint Online supports only the pre-SP2 version of SQL Server 2005.

SQL Azure Support in Office 365 Dedicated Plans Office 365 Dedicated plan customers can use SQL Azure in their SharePoint Online farm with certain restrictions. The following guidelines must be followed when using SQL Azure:  SQL Azure can be used with SharePoint Business Connectivity Services (BCS) to create a Business Data Connectivity (BDC) application. A BDC application can be created in SharePoint Designer to generate an external content type (ECT) for the SQL Azure data. SharePoint Designer can also create a new list based on the ECT, which automatically renders the data in the site. Note that when you create the BDC application, you are required to create a Secure Store Service application definition to encrypt and store the credentials used to connect to SQL Azure. Credentials used to access any SQL Azure database must always be encrypted. For a complete walk-through describing how to use

SharePoint Designer to create a BDC application to SQL Azure, and how to use the Secure Store Service to encrypt the credentials, see Creating an External Content Type Based on SQL Azure in MSDN.  Any components that request data asynchronously from a client application that is hosted in a SharePoint site, such as a Silverlight control, must only retrieve data from the list based on the ECT. We do not support storing connection credentials in a control that is hosted on a client computer, because that assembly can be disassembled and the credentials retrieved.  Components that do not run in a SharePoint page, such as a custom timer job, can make a direct connection to SQL Azure to retrieve data. However, as stated above, the credentials for connecting to SQL Azure must be encrypted and stored in the Secure Store Service. The application can read the credentials out of the Secure Store Service and use that to create the connection string to retrieve data.  Components that run on the server and in a SharePoint page are only allowed to make connections and request data from SQL Azure if the results are cached using a server cache mechanism, such as the ASP.NET Server cache. Queries to SQL Azure are frequently much more latent than queries to a local instance of SQL Server, which is why caching is required. Those requests must also meet the following requirements:  Data must be cached for a minimum of 20 minutes between requests.  Requests must use a lock() pattern when refreshing the cache to ensure that there is no contention for resources or multiple queries executed for the same content.  All connection strings to SQL Azure must use secure connections, as described in How to: Connect to Windows Azure SQL Database Using ADO.NET in the MSDN Library. Here are the important points to remember:  You must include Encrypt = True and TrustServerCertificate = False in the connection string.  Your connection timeout should be at least 30 seconds.  There is one additional configuration change needed to allow connections to SQL Azure from the SharePoint Online farm:  You must get the external IP address for your production farm and, optionally, PPE environments, and add them to the list of allowed IP addresses in the SQL Azure firewall. You can contact your SDM or service manager to open a request to get the IP addresses you should use.

Access Custom Database If your custom solution accesses a custom database, use the Secure Store Service to configure a non- expiring Windows Service account to be stored in encrypted form. Here is an overview of the process for accessing custom databases: 1. Create a non-expiring Windows Service account in the same domain that is trusted by the SharePoint Online farm and that can access the custom database. 2. Grant the account specific rights to the custom database. 3. Create a Secure Store target application, and configure the Windows account as documented in Use Secure Store with SQL Server Authentication (SharePoint Server 2013). In the article, look for these two procedures:  To create a target application for SQL Server authentication  To set credentials for the target application 4. In your code, impersonate the user in the Secure Store Service to access the database.

Non-Supported SQL Server Features

SharePoint Online supports any standard SQL Server features that are used in development practices on SQL Server, except the following:  Integration Services (or any SSIS packages, DTS, BCP)  Reporting Services  Analysis Services  Notification Services  Replication All SQL Server features that are required by the custom design should be detailed in the HLD document for review and approval by Microsoft. Microsoft provides feedback if a feature that the customer plans to use is not supportable. Non-standard features that are also not supported include:  SQL Server 2008 transparent data encryption  SQL Server 2008 data encryption  SQL Server data replication

 Linked server configuration  Cross-database chaining  C2 audit tracing  Common criteria compliance  Server proxy account  Database Mail or SQL Mail  Extended stored procedures (XPs)  Common language runtime (CLR) integration  Ad hoc remote queries (OPENROWSET AND OPENDATASOURCE support)  Native XML web service (HTTP endpoints)  Custom OLE automation  Service broker or message queuing  Web Assistant (as deprecated in SQL 2005)  xp_cmdshell  Custom SQL Server Agent jobs (maintenance jobs already inclusive of the hosting system)  Trace flags  Lightweight pooling

Terms and Conditions

The terms and conditions for hosting a single database for a custom solution are described in this section. If a condition is not listed, this does not mean it is automatically allowed. Contact your SDM for further information.

Database Configuration

Microsoft enforces restrictions on each database. The database cannot grow above 250 GB for SharePoint 2013. The database is configured as follows:  Full recovery model.  Compatibility mode: 100 (SQL Server 2008)  Database ownership is set to sa.

 Database access level for application is set to read/write only.  A single MDF file and a single LDF file.  MDF and LDF data files are located in dedicated Data and Log locations respectively. For example, data files (.mdf) should be placed on H:\MSSQL\Data and log files (.ldf) on O:\MSSQL\DATA.  Data files are initialized at 20 GB for MDF and 5 GB for LDF, with auto-growth set for 200 MB for both file types. Data files are restricted to a maximum size of 80 GB for MDF and 20 GB for LDF.  Remote query timeout is set to 600 seconds.  Not provided: Full-text search is not enabled, and not allowed when co-hosted on the SharePoint Online back end.

Security Model

 Integrated Windows Authentication only.  Not allowed: SQL Server standard logons.  Not provided: SQL Server manages the sa password, which is not provided (disabled).

Database Maintenance

All custom databases will have a maintenance window that is similar to that for SharePoint Online databases:  Weekly full backup  Daily differential backup  15-minute transaction log backup, with file retention of 21 days

High Availability Protection

 Database is mirrored (high-protection mode) within local data center.  Database is log-shipped to remote data center for disaster recovery.

Connectivity and Access

 SQL Server connectivity using TCP/IP protocol only.  Access to SharePoint Online custom database via ADO.NET only; no direct access to server or database via SQL Server Management Studio or the OSQL utility.  Database access level for application is set to Read/Write only.  Not provided: View server state.  Not allowed: the commands create, delete, detach, attach, backup database.

Support

 Custom databases must meet acceptable levels of performance that do not impact SharePoint operations.  Transaction per second < 100.  Reads per transaction (one RPC call) < 100,000.  Not provided: Archive data to tape for long-term retention.

Note: Microsoft reserves the right to implement indexes to improve performance of the database if server performance is impacted by the hosted database.

Using Business Connectivity Services Business Connectivity Services (BCS) is an integration feature of SharePoint 2010 and SharePoint 2013 that provides read and write access to external data in LOB systems, web services, and other external systems. Once an external system has been modeled in BCS, a SharePoint user or developer can create solutions that use external data directly without having to possess expert knowledge about the API of the back-end system. For a more detailed description, see Overview of Business Connectivity Services in SharePoint 2013. Microsoft recommends using Microsoft SharePoint Designer 2010 or SharePoint Designer 2013 to create “code-free” BCS solutions managed by the customer, rather than full trust code solutions managed by Microsoft. This method allows for quicker deployment and easier maintenance. For more information, see Microsoft Business Connectivity Services Model in the Microsoft Download Center. Table 9 lists the CR templates in the order in which they must be submitted.

Table 9. SharePoint CR Templates

CR Template Purpose Comments SPOD-051 (2010/2013) Import Upload the BCS model to the Provides the mapping between BCS Model BCS metadata Store. SharePoint and the external LOB system, and describes the entities and behaviors of the data source.

CR Template Purpose Comments SPOD-054 (2010/2013) Set BCS Identifies the security group that This group must be created so Model Permissions you will add to the Members the users can access the model. field on SPOD-10-168. This template is also used to assign permission to a BCS Model. Users must be assigned permission to access this model. SPOD-168 (2010/2013) Create Creates a new target application. You can define the or Modify a Target Application administrators of the target application. The Member group must be provided. This group uses the credentials set in the target application. Depending on the model’s needs, multiple target applications might need to be created. You must submit an individual CR template for each target application needed.

BCS Solution Authentication Methods Table 10 contains information about supported authentication methods for BCS solutions. For more information, see Available Authentication Modes in the MSDN Library.

Table 10. BCS Authentication

Authentication Method Description Supported?

Authentication Method Description Supported? Pass-Through Authentication Passes the credentials of the logged-on user to the external system. This requires that the user’s credentials are known to the external system. Note: If the Web application is not configured to authenticate with Windows credentials, the NT Authority/Anonymous Logon account is passed to the external system, rather than the user's credentials. This mode is called User’s Identity in the BCS administration pages and in SharePoint Designer 2010 or SharePoint Designer 2013.

Authentication Method Description Supported? RevertToSelf Authentication When the user accesses external data from a web browser, this mode ignores the user’s credentials and sends the application pool identity account under which the BSC runtime is running on the web server to the external system. When the user accesses external data from an Office client application, this mode is equivalent to PassThrough mode, because BCS running on the client will be running under the user’s credentials. This mode is called BDC Identity in the BCS administration pages and in SharePoint Designer 2010 or SharePoint Designer 2013. Note: By default, BDC Identity mode is not enabled. You must use Windows PowerShell to enable BDC Identity mode. BDC Identity mode is not supported in hosted environments.

Authentication Method Description Supported? WindowsCredentials For external web services or X Authentication databases, this mode uses a Secure Store Service to map the user’s credentials to a set of Windows credentials on the external system. This mode is called Impersonate Windows Identity in the BCS administration pages and in SharePoint Designer 2010 or SharePoint Designer 2013. For more information, see Configure the Secure Store Service in SharePoint 2013 and Plan the Secure Store Service in SharePoint Server 2013 in the TechNet library.

Authentication Method Description Supported? Credentials Authentication For an external web service, this X mode uses a Secure Store Service to map the user’s credentials to a set of credentials that are supplied by a source other than Windows, and that are used to access external data. The web service should use basic or digest authentication when this mode is used. Important: To help preserve security in this mode, we recommend that the connection between BCS and the external system should be secured by using Secure Sockets Layer (SSL) or Internet Protocol Security (IPSec). This mode is called Impersonate Custom Identity in BCS administration pages and in SharePoint Designer 2010 or SharePoint Designer 2013.

Authentication Method Description Supported? DigestCredentials Authentication For a WCF web service, this ? mode uses a Secure Store Service to map the user’s credentials to a set of credentials using Digest authentication. This mode is called Impersonate Custom Identity – Digest in BCS administration pages and in SharePoint Designer 2010 or SharePoint Designer 2013.

Customer Responsibilities You must provide the following information to Microsoft when you deploy a BCS solution.  If you are connecting to a SQL Server database on your premises, hosted by a third party or in the cloud, you must provide:  Fully qualified name to SQL Server  IP and port used  Active Directory group name and credentials used to connect to SQL Server  If you are connecting to a web service, you must provide:  Notification of whether WCF or SOAP-based web services are to be used  URL to WSDL file  URI to the service  Provide relevant accounts and groups:  Content Access Account – Account used to access LOB system  User Permissions – Active Directory group containing subset of users or All Authenticated Users  Information Worker (IWs)/Developer Permissions - AD group containing IWs/ Developers that will create and save ECTs

Writing Sandboxed Solutions SharePoint sandboxed solutions are deprecated in SharePoint 2013 in favor of developing apps for SharePoint, but sandboxed solutions can still be installed to site collections on SharePoint 2013. SharePoint 2010 introduced a new type of customization called a sandboxed solution, which uses a restricted set of classes from the SharePoint object model. You can deploy this type of solution to individual site collections without requiring a review by Microsoft. Sandboxed solutions represent a faster deployment path and the opportunity for decentralized customization of individual sites, without the need for centralized ownership or the cooperation of development teams. In those cases where a solution must be deployed as full trust, a sandboxed solution would not be applicable. Sandboxed solutions are packaged as solution files (with a .wsp file extension) that contain assemblies, other non-compiled components, and an XML manifest file. A site collection administrator, or another user with sufficient permissions, can upload the solution package to the solution gallery in the root site of the site collection. All sandboxed solutions are executed in a unique application domain. Because of this, SharePoint 2010 can monitor the performance and resource use of the sandboxed solutions according to various measurements, such as CPU execution time, memory consumption, and unhandled exceptions. These measurements are weighted and combined into a single measure named resource points. Microsoft has set absolute limits, detailed in Table 11, for the number of resource points that sandboxed solutions can use on a per-site collection basis. The available resources are effectively shared among all sandboxed applications in the site collection. The amount of resource usage of the deployed sandboxed solutions can always be seen by the site collection administrator in the Solution Gallery. All sandboxed solutions in a site collection will be terminated if they collectively exceed the set limits. For Microsoft policies on the termination of sandboxed solutions, see Custom Solution Policies and Process (FTC).

Table 11. Resource points for sandboxed solutions

Resource Description Units Resources Absolute per Point Limit (in Points)

Resource Description Units Resources Absolute per Point Limit (in Points) AbnormalProcessTerminationCount Abnormally occurrence 0.25 1 terminated process CPUExecutionTime CPU execution seconds 100 60 time for site CriticalExceptionCount Critical events 10 3 exception events InvocationCount Solution events 100 TBD invocation events PercentProcessorTime Percent CPU percentage 85 100 usage by solution ProcessCPUCycles Solution CPU cycles 40000000000 1 x 10^11 cycles ProcessHandleCount Windows items 10000 5,000 handles count ProcessIOBytes Windows items 10000000 1 x 10^8 handles count ProcessThreadCount Thread count instances 10000 200 in overall process ProcessVirtualBytes Memory bytes 1000000000 1.0 x 10^9 consumed

Resource Description Units Resources Absolute per Point Limit (in Points) SharePointDatabaseQueryCount Number of instances 400 100 SharePoint database queries SharePointDatabaseQueryTime Elapsed time seconds 20 60 to execute query UnhandledExceptionCount Number of instances 25 3 unhandled exceptions UnresponsiveProcessCount Number of instances 2 1 unresponsive processes

Hybrid Solutions In cases where a sandboxed solution is too limited, it is possible to extend the solution by providing mechanisms that allow the solution to call components that are deployed to the SharePoint environment. These mechanisms allow the developer to expose additional SharePoint functionality, to be used from within a sandboxed solution, while maintaining many of the benefits of the sandbox environment. Hybrid solutions are still preferable to complete full trust solutions, because only the full trust portions of the application need to be reviewed by Microsoft. After the full trust components are deployed, they can also be reused by sandbox and declarative solutions later. There are three different types of full-trust components that can be used by a sandboxed solution.  Full-trust proxies. You implement a full-trust proxy in a class that derives from the SPProxyOperation abstract class. That assembly must then be packaged in a solution file and deployed to the global assembly cache in the SharePoint farm. This class then exposes a full-trust proxy that can be called from the sandboxed environment.

Note: You must follow the full custom solution review process when you develop and deploy a full-trust proxy.  External content types. You can use an external content type to retrieve data from LOB applications, and other external sources, through Business Connectivity Services (BCS).

Note: SharePoint Online does not support external content types that require definition of a new single sign-on (SSO) account for accessing the LOB system.

 Custom workflow activities. The declarative workflows within a sandbox environment can use full- trust code-based workflow activities that are deployed to the global assembly cache in the SharePoint farm.

Custom Solution Developer's Guide Appendix Topic Last Modified: 2015-03-09 The appendixes in this topic provide links to additional resources. The appendixes include:  Appendix A: SharePoint Developer Resources  Appendix B: Testing Resources  Appendix C: Custom Solution Deployment Package Checklist  Appendix D: Rules Enforced by MSOCAF  Appendix E: Third-Party Solutions for SharePoint 2013 that Work with SharePoint Online

Appendix A: SharePoint Developer Resources

This appendix offers links to content that may be useful to developers of custom code for SharePoint Online. It also presents a discussion of recommended guidelines for developers. Getting Started The following resources provide a good introduction to the SharePoint platform.

SharePoint 2013 Build apps for SharePoint Learn about SharePoint apps and how to create them. Choose the right API set in SharePoint 2013 Learn about the several sets of APIs that are provided in SharePoint 2013, including the server object model and the various client object models, and the REST/OData web service. SharePoint Developer Center Primary MSDN site for SharePoint developers. SharePoint 2013 Web Services library Web Services available for remote development. SharePoint 2013 Administration Toolkit Details about the SharePoint Administration Toolkit 1.0. SharePoint Server 2013 SDK The software development kit for SharePoint Server 2013. Capacity management and sizing overview for SharePoint Server 2013 Resources to help with capacity management. Software boundaries and limits for SharePoint 2013 Software boundaries that cannot be exceeded by design and thresholds that can be exceeded to accommodate specific requirements. Claims-Based Authentication Resources

There are a number of resources available to learn about claims authentication in general, how it’s used in Microsoft SharePoint 2010, and how to develop claims-aware applications. This list focuses on topics that are most likely to be useful when doing custom claims development for the SharePoint Online environment.  Configuring SharePoint 2010 and Active Directory Federation Services v2 End to End  Configure authentication using a SAML security token (SharePoint Server 2010)  Claims Walkthrough: Writing Claims Providers for SharePoint 2010  Incoming claims: Signing into SharePoint 2013  The Share-n-Dipity Blog

Appendix B: Testing Resources

Testing resources and testing guidelines are identified in this appendix. It also presents a discussion of best practices for testers. Online Resources Checklist for Testing SharePoint Web Parts A 2003 checklist that largely still applies. Testing Your Web Applications for Cross-Site Scripting Vulnerabilities Recommendations about how to handle testing XSS vulnerabilities. Load Testing and Performance Resources Chapter 17 – Load-Testing Web Applications (MSDN Patterns and Practices) General introduction about how to load-test a web application. Load Testing Kit (SharePoint Server 2010) Overview and how-to steps for the Load Testing Kit. Estimate performance and capacity requirements for portal collaboration environments A usage profile example for load testing purposes. Software boundaries and limits for SharePoint 2013 This document describes software boundaries and limits of SharePoint Server 2013.

Appendix C: Custom Solution Deployment Package Checklist

Use this checklist to make sure you have included all necessary documentation in the deployment package before submitting it through MSOCAF. This documentation is required for Microsoft review and validation of the custom solution. MSOCAF validates the structure of the deployment package and checks for all required files, as described in Required Directory Structure and Components in the Deployment Package. The package must be complete and self-contained without references to separate files, documents, or email messages, otherwise the entire package might be rejected.

General Instructions

 Use the most current deployment guide template (available to current customers only, on the Customer Extranet site) to indicate the requirements, planned design, and implementation details for the custom solution.  Prior to submission, ensure that all documents (including embedded documents, if any) open without errors.  Outline what you plan to test and validate (including memory usage, scale, and functionality). It is important that you have validated any third-party products prior to providing the deployment guide to Microsoft. Deployment Guide (Installation Instructions) Include the following installation instructions in your deployment guide:  Detailed instructions for Microsoft to follow when deploying a custom solution, as well as documentation of any unique issues regarding deployment that Microsoft should be aware of. Deployment activities that are automated using the MSOCAF deployment automation framework via DeploymentManifest.xml do not need to be documented.

Note: For third-party products, do not point to the vendor's documentation. You must provide Microsoft with the necessary documentation in this deliverable by providing a completed MSODeploymentGuide.docx document.  (If applicable) The expected duration of down times for deployment configuration and post- deployment configuration of this custom solution. If no downtime is anticipated, indicate 0 minutes.  Instructions for verifying the release, to confirm that the package was properly installed and the custom solution works correctly.  Any architecture diagrams, such as illustrations of dependencies and data flow.  List of any dependencies, such as prerequisite software, related solution deployments, and related standard configurations.  Notation of the presence of open source code, if any open source code is used in the custom solution.

Note: As a part of the deployment guide, the customer is required to provide a waiver in writing that the customer will be responsible for supporting any issues that arise from the open source software.  A list of all design changes, if this design is not the original high-level design (HLD) for this custom solution.  Thorough validation steps for the SharePoint Online operations teams to perform post-deployment. Rollback Plan Each solution package must include a rollback plan in case the deployment must be rolled back, including uninstall and clean-up procedures for any components that are deployed manually.  The previous solution files (.wsp files) to roll back to, if the previous version was not submitted through MSOCAF. The Rollback Process for Remove Configuration Requests

The rollback process is required for Remove Customization Configuration Requests (CRs). This helps prevent service degradation that can occur after performing a remove action. There are two ways to provide rollback steps:

Manual Deployment If your solution was deployed using a manual process (for example, ISV solutions), do the following:

1. Package the solution with removed solution versions, including: a) Deployment scripts and feature activation scripts, located in the Installation Scripts/Rollback folder. b) The Deployment Guide rollback section with instructions on how to run the rollback scripts.

MSOCAF Deployment If your solution was deployed using MSOCAF (for example, customer custom solutions), use the appropriate scenario and approach for the rollback package:

Scenario 1 – Solutions contained within one CR with only one version For solutions that:  Have only one version of the solution deployed to the Pre-production Environment (PPE) and Production Environment and;  Are part of the same CR: 1. Request the “retraction” of the original first version (v1.0) CR through CRAS.

Note The Remove CR process is not supported in this case.

Scenario 2 – Solutions spread across multiple CRs or more than one version of the solution For solutions spread across multiple CRs or if the solutions have more than one previous version (like v2.0, v3.0),:  Package the solution with removed solution versions, including: a) Deployment scripts and feature activation scripts located in the Installation Scripts/Rollback folder. b) The Deployment Guide rollback section with instructions on how to run the rollback scripts

Solution Packages Each solution package must include final tested code for deployment by Microsoft. The code must have been validated with MSOCAF. Test Documents and Results Include details about all elements of the custom solution that you want deployed, including any third- party components and other solutions that you have purchased. This section must include the following test documents:  Test plan that describes what was tested, why it was tested, how it was tested, and whether multiple WFE servers were tested. This should include details about what assumptions were made, and a usage profile or any data points that describe the test environment.  Test scenarios that were tested, and what devices, browsers, latency, or permissions were used in testing. Describe the variations based on audience and presentation requirements.

 Test results that describe what tests were run for feature or functionality testing. This should include which clients were used, what the results were, what dependencies were tested, and what failure situations were tested.  Performance and scale test results that describe what performance or scale tests were run against the custom solution. This should include which usage profile was used and what assumptions were made. Dependencies List Include a list of all dependencies for the code, such as a particular web service, account, database, solution, feature, patch, tool set, or library. Event/ULS Log The event log must include a custom event source with the following components:  Table of all event entries that are generated by the custom solution, with event IDs. Table headings typically include error code, severity, and root cause.  Troubleshooting instructions for all event entries. The ULS log must include the following components:  Category information that identifies the custom solution. Client Troubleshooting Documentation The troubleshooting information must include these two documents:  Troubleshooting guidance for client-facing problems.

Note: For a template that shows the correct format for the client-facing troubleshooting document, see the Troubleshooting Guide Template (available to current customers only, on the Customer Extranet site).  One or two test accounts for diagnosing problems with related dependencies, if appropriate. The account should be a low-privilege account that is used for no other purpose. Source Code All source code must be included in the submission, and must match the current version of the solution packages. Source code is treated with utmost confidentiality by Microsoft. Details about the treatment

of customer source code can be found in the customer's contract, in the "Pre-Existing Work" section. If the solution is a third-party off-the-shelf application, no source code is needed for submission. The source code section must include the following:  Project files (where available)  Source code, validated through MSOCAF  Public debug symbols for all custom code

Note: Ensure that the .zip file format is used for file compression.

Third-Party Licensing Document The licensing document must include:  Any third-party licensing keys or certificates for deployment to the environment.

Note: Be sure to purchase licenses for the primary and secondary data center computers, and for a pre-production environment (PPE), if available.  All details about the testing that has been done against the third-party component or solution. Customer's Security and Compliance Review Document We recommend that you have your own security and compliance teams review and approve all custom solutions that are being presented to Microsoft for deployment. This review document is optional, but if you include one it should contain this information:  The customer's Security and Compliance Review approval of the design.  All test details from this review process. Monitoring Document The monitoring document must include:  All monitoring guidance and details, which must include all information about logging and instrumentation for the custom solution.

Update or Revision to an Existing Custom Solution When you update an existing custom solution and therefore existing documentation, any change to the solution requires submission of a complete new package for review that covers the updated solution. Provide the following components to Microsoft:  Updated versions of all support documents that are detailed earlier in this checklist, such as an update for the end-user troubleshooting guide. Include descriptions of anything that has changed and any design changes and new features that could potentially require support or monitoring.  Summary of changes between current version and previous version, in adequate detail to describe clearly what has changed. (Use the "Changes in This Release" section of the HLD template.)  The original solution source code, for validating against the new source code.  As appropriate, either upgrades steps or uninstall (rollback) information for the previous custom solution, along with an uninstall test that can be run to confirm that the custom solution has been removed.  Details about any problems that are expected to be encountered during the upgrade, such as any errors, rendering issues, or other problems that might be expected when upgrading the custom solution.

Appendix D: Rules Enforced by MSOCAF

MSOCAF validates the custom solution code using a set of rules that are based on established best practices for SharePoint Online custom solutions. These rules are listed in Table 1. Rules marked with an asterisk (*) apply only to SharePoint 2010.

Table 1. MSOCAF validation rules

Rule Tests Against Description

Rule Tests Against Description Use of SPList.Items SPList.Items selects all items from all subfolders, including all fields in the list. This action consumes a significant amount of memory. Instead of using SPList.Items, use SPList.GetItems(SPQuery query). Resolution If the goal is to add a new item, then use the following approach: SPList list = web.Lists["MyList"]; SPQuery query = new SPQuery{Query = "0"}; SPListItemCollection items = list.GetItems(query); SPListItem item = items.Add(); If the goal is to enumerate through a list, then use the following approach: SPList list = web.Lists["MyList"]; SPQuery query = new SPQuery; // Include only the fields you will use. query.ViewFields = ""; query.RowLimit = 2000; // Only select the top 2000. // Include items in subfolder (if necessary). query.ViewAttributes = "Scope=\"Recursive\""; StringBuilder sb = new StringBuilder(); // To make it order by ID and stop scanning the table, specify the OrderBy override attribute. sb.Append(""); //.. Append more text as necessary .. query.Query = sb.ToString(); SPListItemCollection items = list.GetItems(query); If the goal is to get a specific item, then use SPList.Items.GetItemById or SPList.GetItemById(int id, string field1, params string[] fields). For more information, see Best Practices: Common Coding Issues When Using the SharePoint Object Model in the MSDN Library.

Rule Tests Against Description SPListItemCollection\GetItemByID Do not retrieve an instance of an SPListItemCollection inside loop inside a loop. Each time a SPListItemCollection is requested, SharePoint retrieves the items by making a database call. If you need to access an items collection, retrieve it according to the recommendations above and store the result in a variable outside the loop. Resolution Store the Items property return value in a SPListItemCollection variable. The database is queried only once, and then iterates over the result set that is stored within the collection object. SPQuery without Row Limit property Do not use a SPQuery object without setting the Row Limit property. If you use an SPQuery object without specifying the value for the Row Limit property the query returns all items, performs poorly, and even fails on large lists. See the rule “Usage of SPList.Items” in this table for an example of how to implement this. Resolution Specify a Row Limit property when using an SPQuery object. For more information, see Best Practices: Common Coding Issues When Using the SharePoint Object Model in the MSDN Library.

Rule Tests Against Description SPQuery Row Limit value range Do not use an SPQuery object with a Row Limit value beyond the range of 1 to 2000. An SPQuery object without a value for Row Limit performs poorly, and even fails on large lists. Specify a Row Limit between 1 and 2000 and, if necessary, page through the list. Resolution Specify a Row Limit between 1 and 2000 and, if necessary, page through the list. For more details, see Best Practices: Common Coding Issues When Using the SharePoint Object Model in the MSDN Library. Timer jobs MSOCAF verifies that each custom solution that implements a timer job (derived from Microsoft.SharePoint.Administration.SPJobDefinition) is accompanied by a Feature receiver that implements both the FeatureActivated and FeatureDeactivated methods. The FeatureActivated method should contain code that checks to see whether the timer job already exists before creating it. The FeatureDeactivated method should contain code that deletes the timer job. Resolution Ensure that any timer job implementation has FeatureActivated and FeatureDeactivated methods. For more information, see Timer Job in the MSDN Library.

Rule Tests Against Description Out-of-the-box files modification Do not modify the out-of-the-box files with a custom solution. MSOCAF checks that the custom solution does not modify the out-of-box SharePoint files. The only out-of-the- box files that a customer can modify are the document icons displayed in the SharePoint environment, and those must be modified by submitting a configuration request (CR) through the customer’s SDM. Resolution Create new files as necessary in the relevant folder. Verbose logging \ tracing Verbose logging or tracing information can lead to huge log files and affect performance. MSOCAF checks custom solutions make sure they do not turn on verbose logging. Resolution Do not turn on verbose logging or tracing. Deprecated APIs Using deprecated APIs might block migration to newer versions of SharePoint and is therefore not allowed. Resolution Avoid using deprecated APIs in the code. Editing Web config files SharePoint provides access to a web application through the object model using the SPWebApplication class. The SPWebApplication class has a SPWebConfigModifications collection property that contains all the modifications (SPWebConfigModification objects) made to this web application's web.config file. Do not modify web.config by using StreamWriter, XMLDocument, ConfigManager, or XMLTextWriter. Resolution Only modify the web.config file by using the object model.

Rule Tests Against Description Inline code ASPX pages Do not use inline code with full trust on the server, because it is possible for a developer to expose data from anywhere in the SharePoint environment by making a call to elevate the privileges of the code during run time. Resolution Compiled assemblies provide a safer alternative than inline code. For more information, see Inline Code in the MSDN Library. SPListItem.Update() inside loop Do not use SPListItem.Update() inside a loop. Resolution If updates to multiple items are to be made, we recommend using the ProcessBatchData method. This method is designed for processing multiple commands against a SPList without having to open a SPListItemCollection to invoke them. For more information, see SPWeb.ProcessBatchData method in the MSDN Library. SPMonitoredScope Web Part check* Enable SPMonitoredScope for all custom methods of Web Parts (all Functions except OnInit, Render, OnPreRender). Resolution Wrap all code in custom methods with SPMonitoredScope for tracking. For more information, see Using SPMonitoredScope in the MSDN Library. Note: This rule only applies to custom solutions based on SharePoint 2010.

Rule Tests Against Description SPDiagnostics Service Be sure to call SPDiagnosticsService.WriteTrace at start and end of functions in timer jobs, event receivers, Feature receivers, and web services. Resolution ULS logging All exception handlers within a custom solution are required to write to the ULS log. MSOCAF detects whether ULS logging is done in all the catch blocks. Additionally, MSOCAF detects whether calls to unsupported APIs for logging are made. Resolution Write to the ULS log appropriately. For more details, see SPDiagnosticsServiceBase.WriteTrace MethodSPDiagnosticsServiceBase.WriteTrace Method in the MSDN Library. BlobCache value editing in Editing of BlobCache value settings in web.config is web.config prohibited. Resolution Do not edit the BlobCache value settings in web.config. RunWithElevatedPrivileges Elevating privileges of the user must be done securely. All restrictions code is checked for the delegate usage of RunWithElevatedPrivileges and then checked for instructions for file/folder deletion, user profile deletion, or starting/stopping of critical services. Resolution You should not have a RunWithElevatedPrivileges delegate that will perform any of the following tasks:  Deleting file(s) or folder(s)  Deleting user profile(s) from SharePoint Online  Starting or stopping critical services in the SharePoint Online environment

Rule Tests Against Description SharePointQueryWebPartsCheck Errors happening in the Feature receiver on activation and deactivation are logged and thrown back to SharePoint. Windows Claims Check The Windows Claims Check rule flags any code that may break when deployed to a web application in Windows Claims authentication mode. It ensures that any customization using System Namespaces and could fail in Claims mode are flagged. MSOCAF verifies your code for the usage of the following name spaces and will flag them:  Microsoft.SharePoint.SPUser.LoginName  Microsoft.SharePoint.SPUserInfo.LoginName  Microsoft.SharePoint.Utilities.SPPrincipalInfo.LoginName  Microsoft.SharePoint.GetPrincipalsInGroup  System.Security.Principal.WindowsPrincipal.Identity  System.Security.Principal.WindowsIdentity.Name  System.Security.Principal.NTaccount.Value  System.Security.Principal.SecurityIdentifier.Value For information about claims authentication see Windows Claims Authentication.

Appendix E: Third-Party Solutions for SharePoint 2013 that Work with SharePoint Online

Customers that purchase these third-party solutions should determine whether the solution can be deployed without an HLD review. Be sure to note the version number; requests for different versions require a review by Microsoft. For solutions that do not require HLD review, the licensing and other configuration information should be included in the deployment guide.

Any application created by a third party or by another division of Microsoft has not been previously reviewed if it is not included in this list. Thus, it must follow the regular custom solution process to be deployed to a customer's SharePoint Online environment.

List of preapproved third-party solutions

Vendor Preapproved Solution Metalogix Metalogix.SharePoint.Adapters.Extensions – 6.1.0.2 Nintex Nintex Core + other dependent solutions

Approval of third-party solutions for deployment to a customer’s SharePoint Online environment is for compatibility with the SharePoint Online environment only. MICROSOFT IS NOT RESPONSIBLE FOR CUSTOMERS’ USE OR INABILITY TO USE THIRD-PARTY SOLUTIONS AND IS NOT RESPONSIBLE FOR CUSTOMER DATA PROVIDED TO A THIRD-PARTY ISV AT A CUSTOMER’S REQUEST.

Submitting Custom Solutions to SharePoint Online Using MSOCAF Topic Last Modified: 2014-03-07 The Microsoft SharePoint Online Code Analysis Framework (MSOCAF) is the tool you use to validate and submit SharePoint Online custom solutions. MSOCAF includes a set of executable rules to help you analyze custom solutions you plan to deploy to SharePoint Online prior to submitting those solutions for deployment. This means you can identify and address any code issues before submission. The benefits of using MSOCAF include:  You can take care of most of the required code validation early and automatically.  Your custom solution code follows established best practices for both security flaws and memory leaks.  Your custom solution won’t use SharePoint application programming interfaces (APIs) in ways known to cause performance or stability issues  You can validate that your custom solution deploys correctly to your test environment.  After you validate your custom solution and test its deployment, you can use MSOCAF to submit the solution to Microsoft. From a developer’s perspective, here’s what you need to know:  Use MSOCAF to test, analyze, and validate the deployment of custom solutions in the farm environment.  Use MSOCAF to validate all custom solutions developed for SharePoint Online by both customers and independent software vendors (ISVs).  Submit your custom solutions to Microsoft using solution package (.wsp) files. This package must contain:  All the solution files  The deployment guide (MSODeploymentGuide)  The MSOCAF report

 All other package components  The deployment package undergoes testing and review by Microsoft. Testing doesn’t begin until the final code and all documentation have been received. For more information about solution packages and their components, see Custom Solution Policies and Process (FTC) and SharePoint Online Custom Solution Developer's Guide (Dedicated Plans).  If your custom solution passes testing, it is then deployed to the production environment. Video: MSOCAF Overview This video provides an overview of the MSOCAF tool: http://www.bing.com/videos/watch/video/microsoft-sharepoint-online-code-analysis-framework- msocaf-overview/10tksayrq

The Custom Solution Process Topic Last Modified: 2014-02-28 To add or change a full trust code custom solution in the SharePoint Online production environment, follow the development and deployment process that we provide as part of the service. This custom solutions process is based on best practices developed by Microsoft through its work in hosting the SharePoint Online service. To learn more about the custom solution process, see Custom Solution Policies and Process (FTC).

Note: SharePoint Online solution development is moving away from fully-trusted code. As new development scenarios become supported in the service, most will only be available using the Cloud App Model. You should start focusing your development efforts on the same model so you can enjoy the benefits as soon as possible. For more information, see Apps for SharePoint overview.

Installing MSOCAF Topic Last Modified: 2014-02-28 Prerequisites Before installing MSOCAF, make sure:  You have local administrator access to the computer where you will install MSOCAF.  Windows Server 2008 Service Pack 2 (64-bit) or Windows Server 2012 is present on the computer where MSOCAF will be installed.  SharePoint Server 2013 is present on the computer where MSOCAF will be installed.

Note: MSOCAF requires Microsoft .NET Framework 4.5. If .NET Framework 4.5 is not present on the computer when you install MSOCAF, it is installed along with MSOCAF by default.

To Install Using ClickOnce

1. Go to the following location: Microsoft SharePoint Online Code Analysis Framework (MSOCAF). 2. Select I Agree and then click Install.

Note: If .NET Framework 4.5 is not installed, you are prompted to install it.

Note: If you download and save MSOCAF instead of installing it, when you are ready to install it, locate the folder where it was downloaded and then double-click Setup.exe.

3. In the MSOCAF Setup dialog box, click Install.

4. In the Application Install – Security Warning dialog box, click Install.

Note: On 64-bit computers, you might be prompted to restart your computer after the .NET Framework installation completes. To Install Using Offline Installation

1. Click MSOCAF O15-Offline.zip and then open the file when prompted. 2. In Windows Explorer, open the CustomerOffline folder. 3. Right-click Setup.exe and select Run as administrator. 4. Click Yes. 5. Double-click Setup.exe. 6. In the MSOCAF Setup dialog box, click Install.

Note: If .NET Framework 4.5 is not installed, you are prompted to install it. Also note that on 64- bit computers, you might be prompted to restart your computer after the .NET Framework installation completes. 7. On the first page of the MSOCAF Setup Wizard, click Next.

8. In the Folder box, specify the location where you want MSOCAF to be installed on your computer and then click Next.

9. Continue with the installation steps as directed until you reach the end of the wizard.

Uninstalling MSOCAF Topic Last Modified: 2014-02-10 1. In Control Panel, click Programs and Features. 2. Right-click MSOCAF and select Uninstall/Change. 3. In the MSOCAF Maintenance dialog box, ensure Remove this application from this computer is selected and then click OK.

4. Repeat this process for the MSOCAF Event Source. 5. Delete the MSOCAF folder from its installed location. The MSOCAF folder is usually located at \%appdata%\Microsoft Corporation\MSOCAF.

Using MSOCAF Topic Last Modified: 2014-03-28 MSOCAF provides four features to help with your custom solution development and deployment:  Analysis  Test Deployment  Submission  Roll back

Analysis MSOCAF performs a rules-based code analysis of your custom solution to help you use established best practices. MSOCAF uses existing Microsoft Visual Studio components such as FxCop, CAT.NET, and SPDisposeCheck. The report you get back lists things you must fix before submitting your solution.

Analysis focuses on:  Memory management  Security vulnerabilities  Exception management  Object model usage

 Quality gates for unsupported features  Reporting

Test Deployment After you analyze your customer solution and fix all the issues it raises, it’s time to test its deployment to your on-premises test environment. During this test deployment, use the deployment instructions you’ve prepared for your solution. And be sure to note any issues that arise. You will later use your notes to check the accuracy of the deployment instructions for your custom solution before you submit it to Microsoft.

Submission After you successfully validate a custom solution with MSOCAF, you can then submit it to Microsoft.

The following are required for submission:  Email address  Configuration Request (CR) number in the form: CR-XXXX  Customer agreement to the MSOCAF terms

Note: To get the CR number, your service delivery manager (SDM) fills out an offline submission to the Customer Request Analysis System (CRAS) system and then shares the generated number with you.

When you submit the deployment package, MSOCAF does a few final checks and then packages your custom solution into a cabinet (.cab) file, validates the user name and the CR number, and then uploads the .cab file. When the upload is finished, you then receive a confirmation message by email.

Note: The .cab files that you use for automated submission can’t be any larger than 250 megabytes (MB) each. If the .cab file size exceeds this amount, you must submit the package manually to your SDM.

Note:

If the submission fails, MSOCAF creates a local submission package that you can submit to Microsoft manually with the assistance of your SDM. For any additional troubleshooting or questions about MSOCAF, contact [email protected]. For more information about preparing and submitting a custom solution, see SharePoint Online Custom Solution Developer's Guide (Dedicated Plans). Roll back If you run into problems deploying your solution to your test environment, you can roll back the deployment. There are two different ways to do this, Remove and Roll back.  Remove uninstalls the currently deployed components and will not reinstall any earlier versions.  Roll back uninstalls the currently installed version of the components from the farm and installs the previous version components from the last immediate deployment

You can either roll back your test deployment or remove it altogether depending on your preference.

Note: Only the most recent MSOCAF test deployment can be rolled back or removed.

Frequently Asked Questions Topic Last Modified: 2014-02-28 Analysis Wizard  Does the root folder have to be named “Root”?  How and where is the CafPackageResult.cab file created?  Why do I get this MSOCAF error for the SharePointFeatureReciever rule when the code includes a top level try-catch block: “The method does not implement a top level try-catch block”?  Why does MSOCAF crash during .wsp file analysis?  How do I submit a package with third-party binaries if MSOCAF reports that it has a “Security issue”?  How do I fix the issue that causes the error message “Extraction of one or more DLLs failed due to long file name”?  How do I fix the issue that causes the error message “Invalid Manifest”?  Why does MSOCAF generate an exception error when files from the %Programfiles%\Common Files\Microsoft Shared\Web Server Extensions\15\Policy folder are packaged in the .wsp file?  Why does MSOCAF generate an exception error when trying to analyze compatibility mode solutions with MSOCAF 2013? Test Deployment Wizard  Why does the Test Deployment Wizard generate an “Access Denied” error message?  Can I use my own numbers in the Deployment Manifest?  Can I reference a SharePoint Feature by name or only by Feature ID in the FeaturesManifest node of the Deploymentmanifest.xml file?  What are the Web application URL and Backup site owner name values for and where are they located?  How do I fix the deployment error “The Deployment Manifest is not present. The deployment will be marked as skipped”?  Can MSOCAF deploy a custom solution to a remote farm?

 Where do the Manual Retraction/Rollback Steps display if not on the Roll back a deployment page?  Are active hyperlinks allowed on the Post-deployment page?  Where is the MSOCAF deployment log located?  Why can’t I enable a feature with Scope=”Web” during test deployment? Also, why do I get this error in the deployment log when I use Scope=”Site” “Error: Feature ‘AFCEDE87-04DB-4681-9B29- 914CC2582ED0’ is not site scoped”? Submit Wizard  Where is the MSOCAF event log located? Deployment Guide Issues  Why doesn’t the content in the Deployment Guide match the content on the Pre- and Post- deployment pages?  Why don’t hyperlinks appear on the Pre- and Post-deployment pages? Miscellaneous  How do I generate a crash dump for MSOCAF? Analysis Wizard

Does the root folder have to be named “Root”? No, the root folder can have a descriptive name. For example:

How and where is the CafPackageResult.cab file created? To create the CafPackageResult.cab file: 1. In MSOCAF, on the Review your analysis errors page, click Excel. This opens the Excel report created by MSOCAF.

2. Enter the required justifications in the Excel report as shown in the list in the Justified column in MSOCAF.

3. Save this Excel file to the Source Code folder. 4. In MSOCAF, on the Getting started page, click Submit. 5. On the Submit your analyzed code to Microsoft page, browse to the root folder that contains the code you want to submit, enter the required information, agree to the MSOCAF terms, and then click Submit. The CafPackageResult.cab file is created in the \Caf Reports folder.

Note: The submission process is used only to create the .cab file and does not submit your custom solution package to Microsoft.

Why do I get this MSOCAF error for the SharePointFeatureReciever rule when the code includes a top level try-catch block: “The method does not implement a top level try-catch block”? This error message occurs due to conditional loop/using statements. These statements insert an additional try-catch block during compilation (Microsoft Intermediate Language (MSIL) Operation code generation) when MSOCAF performs the analysis. You can ignore this error. In addition, you can override it by entering “False Positive” as the justification. This issue will be fixed in future releases. The following illustrations provide an example of how the error appears in the code.

Why does MSOCAF crash during .wsp file analysis? There is a known issue with CAT.NET regarding the size of .dll files that undergo analysis. You might need to analyze the .dll files on a computer that has more RAM. Here’s some additional information about the required amount of RAM from the CAT.NET 1.1 FAQ: On a 32-bit machine, the total size of the DLLs being analyzed should not exceed 1MB or an Out of Memory exception will be thrown. This is irrespective of how much RAM you have on your machine. On a 64-bit machine you need to have at least 1GB of RAM for each 1MB or more DLLs. For example, if the total size of the .dll files in the package you provided is approximately 12 MB, you need to analyze the package on a computer with at least 12 GB of RAM. The illustration below shows the error you might get in this situation.

How do I submit a package with third-party binaries if MSOCAF reports that it has a “Security issue”? Because you can’t override security rules, you need to provide justifications for all the errors reported by MSOCAF in the analysis errors Excel report. In addition, you need to create the CafPackageResult.cab file and then submit it to Microsoft through your service delivery manager (SDM), using the offline submission process. To create the CafPackageResult.cab file:

1. In MSOCAF, on the Review your analysis errors page, click Excel. This opens the Excel report created by MSOCAF. 2. Enter the required justifications in the Excel report as shown in the list in the Justified column in MSOCAF.

3. Save this Excel file to the Source Code folder. 4. In MSOCAF, on the Getting started page, click Submit. 5. On the Submit your analyzed code to Microsoft page, browse to the root folder that contains the code you want to submit, enter the required information, agree to the MSOCAF terms, and then click Submit. 6. Your submission will fail but the CafPackageResult.cab file is created in the \Caf Reports folder.

After you create the.cab file, submit it to Microsoft through your SDM using the offline submission process.

How do I fix the issue that causes the error message “Extraction of one or more DLLs failed due to long file name? MSOCAF extracts the files in the Solutions Artifacts folder to the User Profile folder (usually found in your %AppData% folder). If these files have long user names, it can prevent MSOCAF from extracting them. To fix this issue, use one of the following options:  Use shorter user names to log onto on the computer where the analysis is performed. See the following illustration as an example.

Or:  Package the .dll files into a single .wsp file rather than individually adding them to the Solutions Artifacts folder.

How do I fix the issue that causes the error message “Invalid Manifest”? There is a mismatch in the.dll file total stored as a value in the tag in the Manifest.xml file, and the actual number of .dll files in your solution package. MSOCAF extracts the .dll files and the Manifest.xml file from the .wsp file in the Solutions Artifacts folder. After extraction, MSOCAF validates the number of .dll files contained in the Manifest.xml file by comparing the .dll file total stored in the tag to the actual number of .dll files in your solution package. If there is a mismatch in these values, MSOCAF generates the “Invalid Manifest” error. To fix this issue: Restructure your package to add all of the .dll files to the Global Assembly Cache (GAC). SharePoint Online policy requires that all of the .dll files present in a solution be added to the GAC because only the .dll files contained in Manifest.xml are added to the GAC.

Why does MSOCAF generate an exception error when files from the %Programfiles%\Common Files\Microsoft Shared\Web Server Extensions\15\Policy folder are packaged in the .wsp file? Files in the %PROGRAMFILES%\Common Files\Microsoft Shared\Web Server Extensions\15\Policy folder can’t be used in a solution package. To fix this issue: Don’t include files from the %PROGRAMFILES%\Common Files\Microsoft Shared\Web Server Extensions\15\Policy folder in the .wsp file.

Why does MSOCAF generate an exception error when trying to analyze compatibility mode solutions with MSOCAF 2013? You might be using MSOCAF 2013 to analyze Microsoft SharePoint 2010 custom solutions. MSOCAF 2013 is not built to analyze SharePoint 2010 custom solutions because of differences in the Microsoft .NET Framework. To fix this issue:

 For analysis: Analyze your SharePoint 2010 custom solution in a SharePoint 2010 farm using MSOCAF 2010. Skip test deployment and submit the package online.  For test deployment: Perform the SharePoint 2010 custom solution test deployment in a SharePoint 2013 farm using MSOCAF 2013 for package validation. Test Deployment Wizard

Why does the Test Deployment Wizard generate an “Access Denied” error message? MSOCAF must be run as an administrator for the Test Deployment Wizard to work correctly. To run MSOCAF as an administrator: 1. Close MSOCAF. 2. Click Start. 3. In the Search field, type cmd, but don’t press the ENTER key. The search results display and cmd.exe is first in the list. 4. In the list, right-click cmd.exe and then select Run as administrator. A command prompt opens. 5. In the command prompt, navigate to the desktop folder of the administrator account (typically CD C:\users\\desktop) and run MSOCAF with the following command: MSOCAF .appref-ms 6. Run the Test Deployment Wizard again.

Can I use my own numbers in the Deployment Manifest? You can use your own version numbers only if they follow this convention:  Version numbers must start with ‘1.0’ and then be incremented in whole numbers onward (for example, 2.0, 3.0, and so on). Custom version numbers, such as Version='1.4.920.40612', are not supported.

Can I reference a SharePoint Feature by name or only by Feature ID in the FeaturesManifest node of the Deploymentmanifest.xml file? You can reference only the Feature ID in the FeaturesManifest node of the Deploymentmanifest.xml file. For example:

What are the Web application URL and Backup site owner name values for and where are they located? The Web application URL is the location MSOCAF uses for the backup of a test deployment package if the deployment is rolled back. It should be located on your local farm. The Backup site owner is a site owner who also has permissions as the site collection administrator. Both of these values are located in Configuration settings on the Options page in MSOCAF as shown in the following illustration.

How do I fix the deployment error “The Deployment Manifest is not present. The deployment will be marked as skipped” You might have a missing DeploymentManifest.xml file. MSOCAF uses the DeploymentManifest.xml file to deploy your custom solutions. If this file is missing from the \Solutions Artifacts folder, you will encounter this error message. For more information about how to create the DeploymentManifest.xml file, see the Test Deployment > Test Deployment > Deployment Manifest section in the MSOCAF Help file (MSOCAF.chm), found in the MSOCAF tool.

Can MSOCAF deploy a custom solution to a remote farm?

No. MSOCAF does not support the deployment of solutions to a remote farm.You must run MSOCAF on the same computer where your SharePoint Online farm is located.

Where do the Manual Retraction/Rollback Steps display if not on the Roll back a deployment page? The instructions for the Manual Retraction/Rollback Steps don’t display on the MSOCAF Roll back a deployment page. They are only located in the Manual Retraction/Rollback Steps found in the MSODeploymentGuide that you submit to Microsoft. The SharePoint Online Operations team follows those instructions during a roll back operation. Ensure that you complete the Manual Retraction/Rollback Steps section before you submit it to Microsoft.

Are active hyperlinks allowed on the Post-deployment page? No. Active hyperlinks aren’t allowed on the Post-deployment page in MSOCAF. To remove active hyperlinks on the Post-deployment page: Right-click the active URL, and then click Remove Hyperlink as shown in the following illustration. Repeat for all active hyperlinks.

After the URLs are no longer hyperlinked, they appear as shown in the following illustration.

Where is the MSOCAF deployment log located? To locate the MSOCAF deployment log: 1. Open MSOCAF. 2. Open the Task Manager. 3. On the Processes tab, right-click MSOCAF and then select Open File Location. 4. In Windows Explorer, open the Logs folder to find the DeploymentLog.log file.

Why can’t I enable a feature with Scope=”Web” during test deployment? Also, why do I get this error in the deployment log

when I use Scope=”Site” “Error: Feature ‘AFCEDE87-04DB-4681- 9B29-914CC2582ED0’ is not site scoped”? MSOCAF doesn’t support deployment of features scoped for a specific web site. The only scope values that are supported for a feature are:  Farm  WebApplication  Site If Scope is set to Web, the feature deployment fails and you’ll get the error message “Error: Feature ‘AFCEDE87-04DB-4681-9B29-914CC2582ED0’ is not site scoped”. To activate the feature for a site collection:  Change the scope from “Web” to “Site” in the Feature.xml file for the solution.  Change the FeatureManifest element in the DeploymentManifest.xml file For more information about activating the feature for a site collection, see the Test Deployment > Test Deployment > Deployment Manifest > FeaturesManifest topic in the MSOCAF Help file (MSOCAF.chm), found in the MSOCAF tool. Submit Wizard

Where is the MSOCAF event log located? To find the MSOCAF event log: 1. Open the Event Viewer. 2. Open the Application and Service Logs folder. The MSOCAF event log file is located in this folder.

Deployment Guide Issues

Why doesn’t the content in the Deployment Guide match the content on the Pre- and Post-deployment pages? There might be duplicate and/or missing content controls in your copy of the MSODeploymentGuide. To check for duplicate or missing content controls in the MSODeploymentGuide: 1. In your copy of the MSODeploymentGuide, customize the ribbon to add the Developer tab by clicking File > Options > Customize Ribbon > Main Tabs > Developer as shown in the following illustration.

2. On the Developer tab, select Design Mode as shown in the following illustration.

3. In MSOCAF, navigate to the Pre-deployment checklist page. 4. To remove any additional content controls, right-click the duplicate control, and then click Remove Content Control.

The following illustration is an example of duplicate content controls.

Why don’t hyperlinks appear on the Pre- and Post-deployment pages? Active hyperlinks aren’t allowed on either the Pre- or Post-deployment pages in MSOCAF. To remove active hyperlinks on the Pre- and Post-deployment pages: Right-click the active URL, and then click Remove Hyperlink as shown in the following illustration. Repeat for all active hyperlinks.

After the URLs are no longer hyperlinked, they appear as shown in the following illustration.

Miscellaneous

How do I generate a crash dump for MSOCAF? To create a crash dump: 1. Download and install the Microsoft Windows SDK for Windows 7 and .NET Framework 4 on the same computer where you run MSOCAF. 2. Run MSOCAF. 3. Create a folder on this computer to store the crash dump. 4. Click Start. 5. In the Search field, type cmd but do not press the ENTER key. The search results will display and cmd.exe will be first in the list. 6. In the list, right-click cmd.exe and then select Run as administrator. A command prompt will open. 7. Navigate to the Debugging Tools for Windows folder. 8. Type the following command into the command prompt and then press ENTER: ‘adplus –crash –o “” –po MSOCAF.exe’ 9. In MSOCAF, click Test Deployment and try to deploy a custom solution. 10. After deployment ends, the crash dump is generated and saved in the folder created in Step 3. Share this folder with Microsoft for further diagnosis.

Additional Resources Topic Last Modified: 2014-03-07  Custom Solution Policies and Process (FTC)  SharePoint Online Custom Solution Developer's Guide (Dedicated Plans)  MSODeploymentGuide