How to: Create a provider-hosted app for SharePoint to access SAP data via SAP Gateway for Microsoft

You can create an app for SharePoint that reads and writes SAP data, and optionally reads and writes SharePoint data, by using SAP Gateway for Microsoft and the Azure AD Authentication Library for .NET. This article provides the procedures for how you can design the app for SharePoint to get authorized access to SAP.

Before you begin

---

The following are prerequisites to the procedures in this article:

• An Office 365 Developer Site in an Office 365 domain that is associated with a Microsoft Azure Active Directory subscription. See Sign up for an Office 365 Developer Subscription, set up your tools and environment, and start deploying apps or How to: Create a Developer Site within your existing Office 365 subscription.
• Visual Studio 2013 Update 2 or later, which you can obtain from Welcome to Visual Studio 2013.
• Microsoft Office Developer Tools for Visual Studio. The version that is included in Update 2 of Visual Studio 2013 or later.
• SAP Gateway for Microsoft is deployed and configured in Microsoft Azure. See the documentation for SAP Gateway for Microsoft.
• An organizational account in Microsoft Azure. See http://msdn.microsoft.com/en-us/library/office/dn605894(v=office.15).aspx#bk_CreateOrganizationAccount.

  Note
  Login to your Office 365 account (login.microsoftonline.com) to change the temporary password after the account is created.

• A SAP OData endpoint with sample data in it. See the documentation for SAP Gateway for Microsoft.

• A basic familiarity with Azure AD. See Getting started with Azure AD.
• A basic familiarity with creating apps for SharePoint. See How to: Create a basic provider-hosted app for SharePoint.
• A basic familiarity OAuth 2.0 in Azure AD. See OAuth 2.0 in Azure AD and its child topics.

Code sample: SharePoint 2013: Using the SAP Gateway to Microsoft in an app for SharePoint

Understand authentication and authorization to SAP Gateway for Microsoft and SharePoint

---

OAuth 2.0 in Azure AD enables applications to access multiple resources hosted by Microsoft Azure and SAP Gateway for Microsoft is one of them. With OAuth 2.0, applications, in addition to users, are security principals. Application principals require authentication and authorization to protected resources in addition to (and sometimes instead of) users. The process involves an OAuth “flow” in which the application, which can be an app for SharePoint, obtains an access token (and refresh token) that is accepted by all of the Microsoft Azure-hosted services and applications that are configured to use Azure AD as an OAuth 2.0 authorization server. The process is very similar to the way that the remote components of a provider-hosted app for SharePoint gets authorization to SharePoint as described in Creating apps for SharePoint that use low-trust authorization and its child articles. However, the ACS authorization system uses Microsoft Azure Access Control Service (ACS) as the trusted token issuer rather than Azure AD.

Tip

If your app for SharePoint accesses SharePoint in addition to accessing SAP Gateway for Microsoft, then it will need to use both systems: Azure AD to get an access token to SAP Gateway for Microsoft and the ACS authorization system to get an access token to SharePoint. The tokens from the two sources are not interchangeable. For more information, see Optionally, add SharePoint access to the ASP.NET application.

For a detailed description and diagram of the OAuth flow used by OAuth 2.0 in Azure AD, see Authorization Code Grant Flow. (For a similar description, and a diagram, of the flow for accessing SharePoint, see See the steps in the Context Token flow.)

Create the app for SharePoint

---

Create the Visual Studio solution

1. Create an App for SharePoint project in Visual Studio with the following steps. (The continuing example in this article assumes you are using C#; but you can start an app for SharePoint project in the Visual Basic section of the new project templates as well.)
   1. In the New app for SharePoint wizard, name the project and click OK. For the continuing example, use SAP2SharePoint.
   2. Specify the domain URL of your Office 365 Developer Site (including a final forward slash) as the debugging site; for example, https://<O365_domain&gt;.sharepoint.com/. Specify Provider-hosted as the app type. Click Next.
   3. Choose a project type. For the continuing example, choose ASP.NET Web Forms Application. (You can also make ASP.NET MVC applications that access SAP Gateway for Microsoft.) Click Next.
   4. Choose Azure ACS as the authentication system. (Your app for SharePoint will use this system if it accesses SharePoint. It does not use this system when it accesses SAP Gateway for Microsoft.) Click Finish.
2. After the project is created, you are prompted to login to the Office 365 account. Use the credentials of an account administrator; for example Bob@<O365_domain>.onmicrosoft.com.
3. There are two projects in the Visual Studio solution; the app for SharePoint proper project and an ASP.NET web forms project. Add the Active Directory Authentication Library (ADAL) package to the ASP.NET project with these steps:
   1. Right-click the References folder in the ASP.NET project (named SAP2SharePointWeb in the continuing example) and select Manage NuGet Packages.
   2. In the dialog that opens, select Online on the left. Enter Microsoft.IdentityModel.Clients.ActiveDirectory in the search box.
   3. When the ADAL library appears in the search results, click the Install button beside it, and accept the license when prompted.
4. Add the Json.net package to the ASP.NET project with these steps:
   1. Enter Json.net in the search box. If this produces too many hits, try searching on Newtonsoft.json.
   2. When Json.net appears in the search results, click the Install button beside it.
5. Click Close.

Register your web application with Azure AD

1. Login into the Azure Management portal with your Azure administrator account.

   Note
   For security purposes, we recommend against using an administrator account when developing apps.

2. Choose Active Directory on the left side.
3. Click on your directory.
4. Choose APPLICATIONS (on the top navigation bar).
5. Choose Add on the toolbar at the bottom of the screen.
6. On the dialog that opens, choose Add an application my organization is developing.
7. On the ADD APPLICATION dialog, give the application a name. For the continuing example, use ContosoAutomobileCollection.
8. Choose Web Application And/Or Web API as the application type, and then click the right arrow button.
9. On the second page of the dialog, use the SSL debugging URL from the ASP.NET project in the Visual Studio solution as the SIGN-ON URL. You can find the URL using the following steps. (You need to register the app initially with the debugging URL so that you can run the Visual Studio debugger (F5). When your app is ready for staging, you will re-register it with its staging Azure Web Site URL. Modify the app and stage it to Azure and Office 365.)
   1. Highlight the ASP.NET project in Solution Explorer.
   2. In the Properties window, copy the value of the SSL URL property. An example is https://localhost:44300/.
   3. Paste it into the SIGN-ON URL on the ADD APPLICATION dialog.
10. For the APP ID URI, give the application a unique URI, such as the application name appended to the end of the SSL URL; for example https://localhost:44300/ContosoAutomobileCollection.
11. Click the checkmark button. The Azure dashboard for the application opens with a success message.
12. Choose CONFIGURE on the top of the page.
13. Scroll to the CLIENT ID and make a copy of it. You will need it for a later procedure.
14. In the keys section, create a key. It won’t appear initially. Click SAVE at the bottom of the page and the key will be visible. Make a copy of it. You will need it for a later procedure.
15. Scroll to permissions to other applications and select your SAP Gateway for Microsoft service application.
16. Open the Delegated Permissions drop down list and enable the boxes for the permissions to the SAP Gateway for Microsoft service that your app for SharePoint will need.
17. Click SAVE at the bottom of the screen.

Configure the application to communicate with Azure AD

1. In Visual Studio, open the web.config file in the ASP.NET project.
2. In the <appSettings> section, the Office Developer Tools for Visual Studio have added elements for the ClientID and ClientSecret of the app for SharePoint. (These are used in the Azure ACS authorization system if the ASP.NET application accesses SharePoint. You can ignore them for the continuing example, but do not delete them. They are required in provider-hosted apps for SharePoint even if the app is not accessing SharePoint data. Their values will change each time you press F5 in Visual Studio.) Add the following two elements to the section. These are used by the application to authenticate to Azure AD. (Remember that applications, as well as users, are security principals in OAuth-based authentication and authorization systems.)
   <add key="ida:ClientID" value="" />
   <add key="ida:ClientKey" value="" />
   

3. Insert the client ID that you saved from your Azure AD directory in the earlier procedure as the value of the ida:ClientID key. Leave the casing and punctuation exactly as you copied it and be careful not to include a space character at the beginning or end of the value. For the ida:ClientKey key use the key that you saved from the directory. Again, be careful not to introduce any space characters or change the value in any way. The <appSettings> section should now look something like the following. (The ClientId value may have a GUID or an empty string.)
   <appSettings>
     <add key="ClientId" value="" />
     <add key="ClientSecret" value="LypZu2yVajlHfPLRn5J2hBrwCk5aBOHxE4PtKCjIQkk=" />
     <add key="ida:ClientID" value="4da99afe-08b5-4bce-bc66-5356482ec2df" />
     <add key="ida:ClientKey" value="URwh/oiPay/b5jJWYHgkVdoE/x7gq3zZdtcl/cG14ss=" />
   </appSettings>
   

   Note
   Your application is known to Azure AD by the “localhost” URL you used to register it. The client ID and client key are associated with that identity. When you are ready to stage your application to an Azure Web Site, you will re-register it with a new URL.

4. Still in the appSettings section, add an Authority key and set its value to the Office 365 domain (some_domain.onmicrosoft.com) of your organizational account. In the continuing example, the organizational account is Bob@<O365_domain>.onmicrosoft.com, so the authority is <O365_domain>.onmicrosoft.com.
   <add key="Authority" value="<O365_domain>.onmicrosoft.com" />
   

5. Still in the appSettings section, add an AppRedirectUrl key and set its value to the page that the user’s browser should be redirected to after the ASP.NET app has obtained an authorization code from Azure AD. Usually, this is the same page that the user was on when the call to Azure AD was made. In the continuing example, use the SSL URL value with “/Pages/Default.aspx” appended to it as shown below. (This is another value that you will change for staging.)
   Copy

   <add key="AppRedirectUrl" value="https://localhost:44322/Pages/Default.aspx" />
   

6. Still in the appSettings section, add a ResourceUrl key and set its value to the APP ID URI of SAP Gateway for Microsoft (not the APP ID URI of your ASP.NET application). Obtain this value from the SAP Gateway for Microsoft administrator. The following is an example.
   <add key="ResourceUrl" value="http://<SAP_gateway_domain>.cloudapp.net/" />
   

   The <appSettings> section should now look something like this:

   <appSettings>
     <add key="ClientId" value="06af1059-8916-4851-a271-2705e8cf53c6" />
     <add key="ClientSecret" value="LypZu2yVajlHfPLRn5J2hBrwCk5aBOHxE4PtKCjIQkk=" />
     <add key="ida:ClientID" value="4da99afe-08b5-4bce-bc66-5356482ec2df" />
     <add key="ida:ClientKey" value="URwh/oiPay/b5jJWYHgkVdoE/x7gq3zZdtcl/cG14ss=" />
     <add key="Authority" value="<O365_domain>.onmicrosoft.com" />
     <add key="AppRedirectUrl" value="https://localhost:44322/Pages/Default.aspx" />
     <add key="ResourceUrl" value="http://<SAP_gateway_domain>.cloudapp.net/" />
   </appSettings>
   

7. Save and close the web.config file.

   Tip
   Do not leave the web.config file open when you run the Visual Studio debugger (F5). The Office Developer Tools for Visual Studio change the ClientId value (not the ida:ClientID) every time you press F5. This requires you to respond to a prompt to reload the web.config file, if it is open, before debugging can execute.

Add a helper class to authenticate to Azure AD

1. Right-click the ASP.NET project and use the Visual Studio item adding process to add a new class file to the project named AADAuthHelper.cs.
2. Add the following using statements to the file.
   using Microsoft.IdentityModel.Clients.ActiveDirectory;
   using System.Configuration;
   using System.Web.UI;
   
   

3. Change the access keyword from public to internal and add the static keyword to the class declaration.
   internal static class AADAuthHelper
   

4. Add the following fields to the class. These fields store information that your ASP.NET application uses to get access tokens from AAD.
   private static readonly string _authority = ConfigurationManager.AppSettings["Authority"];
   private static readonly string _appRedirectUrl = ConfigurationManager.AppSettings["AppRedirectUrl"];
   private static readonly string _resourceUrl = ConfigurationManager.AppSettings["ResourceUrl"];     
           
   private static readonly ClientCredential _clientCredential = new ClientCredential(
                              ConfigurationManager.AppSettings["ida:ClientID"],
                              ConfigurationManager.AppSettings["ida:ClientKey"]);
   
   private static readonly AuthenticationContext _authenticationContext = 
               new AuthenticationContext("https://login.windows.net/common/" + 
                                         ConfigurationManager.AppSettings["Authority"]);
   

5. Add the following property to the class. This property holds the URL to the Azure AD login screen.
   private static string AuthorizeUrl
   {
       get
       {
           return string.Format("https://login.windows.net/{0}/oauth2/authorize?response_type=code&redirect_uri={1}&client_id={2}&state={3}",
               _authority,
               _appRedirectUrl,
               _clientCredential.OwnerId,
               Guid.NewGuid().ToString());
       }
   }
   
   

6. Add the following properties to the class. These cache the access and refresh tokens and check their validity.
   public static Tuple<string, DateTimeOffset> AccessToken
   {
       get {
   return HttpContext.Current.Session["AccessTokenWithExpireTime-" + _resourceUrl] 
          as Tuple<string, DateTimeOffset>;
       }
   
       set { HttpContext.Current.Session["AccessTokenWithExpireTime-" + _resourceUrl] = value; }
   }
   
   private static bool IsAccessTokenValid
   {
      get 
      { 
          return AccessToken != null &&
          !string.IsNullOrEmpty(AccessToken.Item1) &&
          AccessToken.Item2 > DateTimeOffset.UtcNow;
      }
   }
   
   private static string RefreshToken
   {
       get { return HttpContext.Current.Session["RefreshToken" + _resourceUrl] as string; }
       set { HttpContext.Current.Session["RefreshToken-" + _resourceUrl] = value; }
   }
   
   private static bool IsRefreshTokenValid
   {
       get { return !string.IsNullOrEmpty(RefreshToken); }
   }
   
   

7. Add the following methods to the class. These are used to check the validity of the authorization code and to obtain an access token from Azure AD by using either an authentication code or a refresh token.
   private static bool IsAuthorizationCodeNotNull(string authCode)
   {
       return !string.IsNullOrEmpty(authCode);
   }
   
   private static Tuple<Tuple<string,DateTimeOffset>,string> AcquireTokensUsingAuthCode(string authCode)
   {
       var authResult = _authenticationContext.AcquireTokenByAuthorizationCode(
                   authCode,
                   new Uri(_appRedirectUrl),
                   _clientCredential,
                   _resourceUrl);
   
       return new Tuple<Tuple<string, DateTimeOffset>, string>(
                   new Tuple<string, DateTimeOffset>(authResult.AccessToken, authResult.ExpiresOn), 
                   authResult.RefreshToken);
   }
   
   private static Tuple<string, DateTimeOffset> RenewAccessTokenUsingRefreshToken()
   {
       var authResult = _authenticationContext.AcquireTokenByRefreshToken(
                            RefreshToken,
                            _clientCredential.OwnerId,
                            _clientCredential,
                            _resourceUrl);
   
       return new Tuple<string, DateTimeOffset>(authResult.AccessToken, authResult.ExpiresOn);
   }
   
   

8. Add the following method to the class. It is called from the ASP.NET code behind to obtain a valid access token before a call is made to get SAP data via SAP Gateway for Microsoft.
   internal static void EnsureValidAccessToken(Page page)
   {
       if (IsAccessTokenValid) 
       {
           return;
       }
       else if (IsRefreshTokenValid) 
       {
           AccessToken = RenewAccessTokenUsingRefreshToken();
           return;
       }
       else if (IsAuthorizationCodeNotNull(page.Request.QueryString["code"]))
       {
           Tuple<Tuple<string, DateTimeOffset>, string> tokens = null;
           try
           {
               tokens = AcquireTokensUsingAuthCode(page.Request.QueryString["code"]);
           }
           catch 
           {
               page.Response.Redirect(AuthorizeUrl);
           }
           AccessToken = tokens.Item1;
           RefreshToken = tokens.Item2;
           return;
       }
       else
       {
           page.Response.Redirect(AuthorizeUrl);
       }
   }
   

Tip
The AADAuthHelper class has only minimal error handling. For a robust, production quality app for SharePoint, add more error handling as described in this MSDN node: Error Handling in OAuth 2.0.

Create data model classes

1. Create one or more classes to model the data that your app gets from SAP. In the continuing example, there is just one data model class. Right-click the ASP.NET project and use the Visual Studio item adding process to add a new class file to the project named Automobile.cs.
2. Add the following code to the body of the class:
   public string Price;
   public string Brand;
   public string Model;
   public int Year;
   public string Engine;
   public int MaxPower;
   public string BodyStyle;
   public string Transmission;
   

Add code behind to get data from SAP via the SAP Gateway for Microsoft

1. Open the Default.aspx.cs file and add the following using statements.
   using System.Net;
   using Newtonsoft.Json.Linq;
   

2. Add a const declaration to the Default class whose value is the base URL of the SAP OData endpoint that the app will be accessing. The following is an example:
   private const string SAP_ODATA_URL = @"https://<SAP_gateway_domain>.cloudapp.net:8081/perf/sap/opu/odata/sap/ZCAR_POC_SRV/";
   

3. The Office Developer Tools for Visual Studio have added a Page_PreInit method and a Page_Load method. Comment out the code inside the Page_Load method and comment out the whole Page_Init method. This code is not used in this sample. (If your app for SharePoint is going to access SharePoint, then you restore this code. See Optionally, add SharePoint access to the ASP.NET application.)
4. Add the following line to the top of the Page_Load method. This will ease the process of debugging because your ASP.NET application is communicating with SAP Gateway for Microsoft using SSL (HTTPS); but your “localhost:port” server is not configured to trust the certificate of SAP Gateway for Microsoft. Without this line of code, you would get an invalid certificate warning before Default.aspx will open. Some browsers allow you to click past this error, but some will not let you open Default.aspx at all.
   ServicePointManager.ServerCertificateValidationCallback = (s, cert, chain, errors) => true;
   

   Important
   Delete this line when you are ready to deploy the ASP.NET application to staging. See Modify the app and stage it to Azure and Office 365.

5. Add the following code to the Page_Load method. The string you pass to the GetSAPData method is an OData query.
   if (!IsPostBack)
   {
       GetSAPData("DataCollection?$top=3");
   }
   
   

6. Add the following method to the Default class. This method first ensures that the cache for the access token has a valid access token in it that has been obtained from Azure AD. It then creates an HTTP GET Request that includes the access token and sends it to the SAP OData endpoint. The result is returned as a JSON object that is converted to a .NET List object. Three properties of the items are used in an array that is bound to the DataListView.
   private void GetSAPData(string oDataQuery)
   {
       AADAuthHelper.EnsureValidAccessToken(this);
   
       using (WebClient client = new WebClient())
       {
           client.Headers[HttpRequestHeader.Accept] = "application/json";
           client.Headers[HttpRequestHeader.Authorization] = "Bearer " + AADAuthHelper.AccessToken.Item1;
           var jsonString = client.DownloadString(SAP_ODATA_URL + oDataQuery);
           var jsonValue = JObject.Parse(jsonString)["d"]["results"];
           var dataCol = jsonValue.ToObject<List<Automobile>>();
   
           var dataList = dataCol.Select((item) => {
               return item.Brand + " " + item.Model + " " + item.Price;
               }).ToArray();
   
           DataListView.DataSource = dataList;
           DataListView.DataBind();
       }
   }
   
   

Create the user interface

1. Open the Default.aspx file and add the following markup to the form of the page:
   <div>
     <h3>Data from SAP via SAP Gateway for Microsoft</h3>
   
     <asp:ListView runat="server" ID="DataListView">
       <ItemTemplate>
         <tr runat="server">
           <td runat="server">
             <asp:Label ID="DataLabel" runat="server"
               Text="<%# Container.DataItem.ToString()%>" /><br />
           </td>
         </tr>
       </ItemTemplate>
     </asp:ListView>
   </div>
   

2. Optionally, give the web page the “look ‘n’ feel” of a SharePoint page with the SharePoint Chrome Control and the host SharePoint website’s style sheet.

Test the app with F5 in Visual Studio

1. Press F5 in Visual Studio.
2. The first time that you use F5, you may be prompted to login to the Developer Site that you are using. Use the site administrator credentials. In the continuing example, it is Bob@<O365_domain>.onmicrosoft.com.
3. The first time that you use F5, you are prompted to grant permissions to the app. Click Trust It.
4. After a brief delay while the access token is being obtained, the Default.aspx page opens. Verify that the SAP data appears.

Optionally, add SharePoint access to the ASP.NET application

---

Of course, your app for SharePoint doesn’t have to expose only SAP data in a web page launched from SharePoint. It can also create, read, update, and delete (CRUD) SharePoint data. Your code behind can do this using either the SharePoint client object model (CSOM) or the REST APIs of SharePoint. The CSOM is deployed as a pair of assemblies that the Office Developer Tools for Visual Studio automatically included in the ASP.NET project and set to Copy Local in Visual Studio so that they are included in the ASP.NET application package. For information about using CSOM, start with How to: Complete basic operations using SharePoint 2013 client library code. For information about using the REST APIs, start with Understanding and Using the SharePoint 2013 REST Interface.Regardless, of whether you use CSOM or the REST APIs to access SharePoint, your ASP.NET application must get an access token to SharePoint, just as it does to SAP Gateway for Microsoft. See Understand authentication and authorization to SAP Gateway for Microsoft and SharePoint above. The procedure below provides some basic guidance about how to do this, but we recommend that you first read the following articles:

• How to: Create a basic provider-hosted app for SharePoint
• Authorization and authentication of apps for SharePoint 2013
• Three authorization systems for apps for SharePoint 2013
• Creating apps for SharePoint that use low-trust authorization
• Context Token OAuth flow for apps in SharePoint 2013

1. Open the Default.aspx.cs file and uncomment the Page_PreInit method. Also uncomment the code that the Office Developer Tools for Visual Studio added to the Page_Load method.
2. If your app for SharePoint is going to access SharePoint data, then you have to cache the SharePoint context token that is POSTed to the Default.aspx page when the app is launched in SharePoint. This is to ensure that the SharePoint context token is not lost when the browser is redirected following the Azure AD authentication. (You have several options for how to cache this context. See OAuth tokens.) The Office Developer Tools for Visual Studio add a SharePointContext.cs file to the ASP.NET project that does most of the work. To use the session cache, you simply add the following code inside the “if (!IsPostBack)” block before the code that calls out to SAP Gateway for Microsoft:
   if (HttpContext.Current.Session["SharePointContext"] == null) 
   {
        HttpContext.Current.Session["SharePointContext"]
           = SharePointContextProvider.Current.GetSharePointContext(Context);
   }
   

3. The SharePointContext.cs file makes calls to another file that the Office Developer Tools for Visual Studio added to the project: TokenHelper.cs. This file provides most of the code needed to obtain and use access tokens for SharePoint. However, it does not provide any code for renewing an expired access token or an expired refresh token. Nor does it contain any token caching code. For a production quality app for SharePoint, you need to add such code. The caching logic in the preceding step is an example. Your code should also cache the access token and reuse it until it expires. When the access token is expired, your code should use the refresh token to get a new access token. We recommend that you read OAuth tokens.
4. Add the data calls to SharePoint using either CSOM or REST. The following example is a modification of CSOM code that Office Developer Tools for Visual Studio adds to the Page_Load method. In this example, the code has been moved to a separate method and it begins by retrieving the cached context token.
   Copy

   private void GetSharePointTitle()
   {
       var spContext = HttpContext.Current.Session["SharePointContext"] as SharePointContext;
       using (var clientContext = spContext.CreateUserClientContextForSPHost())
       {
           clientContext.Load(clientContext.Web, web => web.Title);
           clientContext.ExecuteQuery();
           SharePointTitle.Text = "SharePoint web site title is: " + clientContext.Web.Title;
       }
   }
   

5. Add UI elements to render the SharePoint data. The following shows the HTML control that is referenced in the preceding method:
   <h3>SharePoint title</h3><asp:Label ID="SharePointTitle" runat="server"></asp:Label><br />
   

Note
While you are debugging the app for SharePoint, the Office Developer Tools for Visual Studio re-register it with Azure ACS each time you press F5 in Visual Studio. When you stage the app for SharePoint, you have to give it a long-term registration. See the section Modify the app and stage it to Azure and Office 365.

Modify the app and stage it to Azure and Office 365

---

When you have finished debugging the app for SharePoint using F5 in Visual Studio, you need to deploy the ASP.NET application to an actual Azure Web Site.

Create the Azure Web Site

1. In the Microsoft Azure portal, open WEB SITES on the left navigation bar.
2. Click NEW at the bottom of the page and on the NEW dialog select WEB SITE | QUICK CREATE.
3. Enter a domain name and click CREATE WEB SITE. Make a copy of the new site’s URL. It will have the form my_domain.azurewebsites.net.

Modify the code and markup in the application

1. In Visual Studio, remove the line ServicePointManager.ServerCertificateValidationCallback = (s, cert, chain, errors) => true; from the Default.aspx.cs file.
2. Open the web.config file of the ASP.NET project and change the domain part of the value of the AppRedirectUrl key in the appSettings section to the domain of the Azure Web Site. For example, change <add key=”AppRedirectUrl” value=”https://localhost:44322/Pages/Default.aspx&#8221; /> to <add key=”AppRedirectUrl” value=”https://my_domain.azurewebsites.net/Pages/Default.aspx&#8221; />.
3. Right-click the AppManifest.xml file in the app for SharePoint project and select View Code.
4. In the StartPage value, replace the string ~remoteAppUrl with the full domain of the Azure Web Site including the protocol; for example https://my_domain.azurewebsites.net. The entire StartPage value should now be: https://my_domain.azurewebsites.net/Pages/Default.aspx. (Usually, the StartPage value is exactly the same as the value of the AppRedirectUrl key in the web.config file.)

Modify the AAD registration and register the app with ACS

1. Login into Azure Management portal with your Azure administrator account.
2. Choose Active Directory on the left side.
3. Click on your directory.
4. Choose APPLICATIONS (on the top navigation bar).
5. Open the application you created. In the continuing example, it is ContosoAutomobileCollection.
6. For each of the following values, change the “localhost:port” part of the value to the domain of your new Azure Web Site:
   • SIGN-ON URL
   • APP ID URI
   • REPLY URL

   For example, if the APP ID URI is https://localhost:44304/ContosoAutomobileCollection, change it to https://<my_domain&gt;.azurewebsites.net/ContosoAutomobileCollection.

7. Click SAVE at the bottom of the screen.
8. Register the app with Azure ACS. This must be done even if the app does not access SharePoint and will not use tokens from ACS, because the same process also registers the app with the App Management Service of the Office 365 subscription, which is a requirement. You perform the registration on the AppRegNew.aspx page of any SharePoint website in the Office 365 subscription. For details, see Guidelines for registering apps for SharePoint 2013. As part of this process you will obtain a new client ID and client secret. Insert these values in the web.config for the ClientId (not ida:ClientID) and ClientSecret keys.

   Caution
   If for any reason you press F5 after making this change, the Office Developer Tools for Visual Studio will overwrite one or both of these values. For that reason, you should keep a record of the values obtained with AppRegNew.aspx and always verify that the values in the web.config are correct just before you publish the ASP.NET application.

Publish the ASP.NET application to Azure and install the app to SharePoint

1. There are several ways to publish an ASP.NET application to an Azure Web Site. For more information, see How to Deploy an Azure Web Site.
2. In Visual Studio, right-click the SharePoint app project and select Package. On the Publish your app page that opens, click Package the app. File explorer opens to the folder with the app package.
3. Login to Office 365 as a global administrator, and navigate to the organization app catalog site collection. (If there isn’t one, create it. See Use the App Catalog to make custom business apps available for your SharePoint Online environment.)
4. Upload the app package to the app catalog.
5. Navigate to the Site Contents page of any website in the subscription and click add an app.
6. On the Your Apps page, scroll to the Apps you can add section and click the icon for your app.
7. After the app has installed, click it’s icon on the Site Contents page to launch the app.

For more information about installing apps for SharePoint, see Deploying and installing apps for SharePoint: methods and options.

Deploying the app to production

---

When you have finished all testing you can deploy the app in production. This may require some changes.

1. If the production domain of the ASP.NET application is different from the staging domain, you will have to change AppRedirectUrl value in the web.config and the StartPage value in the AppManifest.xml file, and repackage the app for SharePoint. See the procedure Modify the code and markup in the application above.
2. The change in domain also requires that you edit the apps registration with AAD. See the procedure Modify the AAD registration and register the app with ACS above.
3. The change in domain also requires that you re-register the app with ACS (and the subscription’s App Management Service) as described in the same procedure. (There is no way to edit an app’s registration with ACS.) However, it is not necessary to generate a new client ID or client secret on the AppRegNew.aspx page. You can copy the original values from the ClientId (not ida:ClientID) and ClientSecret keys of the web.config into the AppRegNew form. If you do generate new ones, be sure to copy the new values to the keys in web.config.

How To : Add a Promoted Links Web Part to SharePoint 2013 App Default page

This article helps you to add Promoted links web part to your default app page as the following figure:

 

To do this follow the following steps:

Open the shortcut menu for the project, and then choose Add, New Item

 

In the Templates pane, choose the List template, and then choose the Add button :

Enter list name and choose the Create a non-customizable list based on an existing list type of option button, and then, in its list, choose Promoted links, and then choose the Finish button

In Solution Explorer, under the list instance node, open the Elements.xml file.

Add the promoted links items as the following:

<?versionencodingutf-8?>

Elementsxmlnshttp://schemas.microsoft.com/sharepoint/

ListInstanceTitleMyPromotedLinks

OnQuickLaunch

TemplateType

FeatureId192efa95-e50c-475e-87ab-361cede5dd7f

Lists/MyPromotedLinks

DescriptionMy List Instance

FieldTitleTwitter</Field

FieldBackgroundImageLocation/PromotedLinksApp/Images/twitter.png

FieldDescriptionMuawiyah Shannak Twitter

FieldLinkLocationhttps://twitter.com/MuShannak</Field

FieldOrder</Field

</

FieldTitle</Field

FieldBackgroundImageLocation/PromotedLinksApp/Images/blogger.png

FieldDescriptionMuawiyah Shannak Blog

FieldLinkLocationhttp://mushannak.blogspot.com</Field

FieldOrder</Field

</

FieldTitleLinkedin</Field

FieldBackgroundImageLocation/PromotedLinksApp/Images/linkedin.png

FieldDescriptionMuawiyah Shannak Linkedin

FieldLinkLocationhttp://ae.linkedin.com/in/shannak</Field

FieldOrder</Field

</

</

</

<!–ListInstance

</Elements

In Solution Explorer, under the Pages node, open the Default.aspx file. Add following tags inside the PlaceHolderMain Place Holder:

WebPartPagesWebPartZone=”WebPartZone”runat=”server”FrameType=”None”>

WebPartPagesXsltListViewWebPart=”XsltListViewAppPromotedList”

runat=”server”ListUrl=”Lists/MyPromotedLinks”IsIncluded=”True”

NoDefaultStyle=”TRUE”Title=”Images used in switcher”

PageType=”PAGE_NORMALVIEW”Default=”False”

ViewContentTypeId=”0x”>

</WebPartPagesXsltListViewWebPart

</WebPartPagesWebPartZone

Deploy a solution and you will find nice promoted links web part in the app default page!

New Highly Customisable SharePoint CRM Template Available

A CRM/Project Management Site Template for SharePoint 2010 Enterprise or SharePoint Online tenants.
This extensive solution offers the following features:

• User Friendly – Due to a custom User Interface & Pre-Populated InfoPath forms where possible
• Contacts Management
• Project Management – Associated sub tasks, documents & sales
• Products & Services Catalog
• Sales Register & Invoice Generation
• Client Enquiry – Showing any items related to a client
• Reporting
• Integrated User Guide

To give you an idea of how SharePoint CRM looks, below is a selection of screenshots:

Home Screen

The buttons displayed are defined by a list within SharePoint CRM so can easily be modified.

Contacts

Project Management

Sales Register

Being SharePoint all aspects of the SharePoint CRM Template can be customised to meet your organisations needs:

For example, to customise the home page :

Customising your homepage

Rather than the buttons on the homepage being hardcoded, they are defined by a list within the CRM site. This means you can easily add/remove/edit buttons using just your web browser, here’s how to do so:

1. From the Site Actions, choose View All Site Content
2. Open the PortalMenu list

Items can then be edited in the same way as any other SharePoint 2010 list, below is a description of options available:

• Section – Defines which section the button will be shown in on your homepage
• Order – Defines the order of the buttons within a section
• Button Name – The text that will be displayed within the button
• Link – The URL that users will be taken to when the button is clicked
• Hover – The text shown when a user hovers over a button
• Dialog – Specifies whether the page that the button links to will open in a popup dialog box
• New Project Form – If this option is checked the Link field will be ignored an the button will open the new project form.

Adding new Sections

New sections can be added to the homepage, but will required the use of SharePoint Designer to do so:

1. Open the PortalMenu list as described above, the go to the List Settings page
2. Edit the Section column, then add the name of your new section as a choice
3. Create a new list item with your new choice set within the Section field
4. Navigate to your homepage, and set the page to edit mode
5. Export any sections web part, then import the web part and add it to any zone
6. Using SharePoint Designer open the homepage (SitePages\default.aspx)
7. Select the new web part, the update the filter to match the new choice you added to the section column

This template and other SharePoint Web Parts, Apps, Custom SharePoint Templates, Tools for SharePoint, Azure and Office365 is available by contacting me through my website at http://sharepointsamurai,wordpress.com/ 

Name(required)

Email(required)

Company(required)

Comment(required)

Submit

Δ

Free Code to Create Cross-site Publishing Apps for SharePoint Online

Cross-site publishing is one of the powerful new capabilities in SharePoint 2013.  It enables the separation of data entry from display and breaks down the container barriers that have traditionally existed in SharePoint (ex: rolling up information across site collections). 

 

Cross-site publishing is delivered through search and a number of new features, including list/library catalogs, catalog connections, and the content search web part.  Unfortunately, SharePoint Online/Office 365 doesn’t currently support these features.  Until they are added to the service (possibly in a quarterly update), customers will be looking for alternatives to close the gap.  In this post, I will outline several alternatives for delivering cross-site and search-driven content in SharePoint Online and how to template these views for reuse

I’m a huge proponent of SharePoint Online.  After visiting several Microsoft data centers, I feel confident that Microsoft is better positioned to run SharePoint infrastructure than almost any organization in the world.  SharePoint Online has very close feature parity to SharePoint on-premise, with the primary gaps existing in cross-site publishing and advanced business intelligence.  Although these capabilities have acceptable alternatives in the cloud (as will be outlined in this post), organizations looking to maximize the cloud might consider SharePoint running in IaaS for immediate access to these features.

 

Apps for SharePoint

The new SharePoint app model is fully supported in SharePoint Online and can be used to deliver customizations to SharePoint using any web technology.  New SharePoint APIs can be used with the app model to deliver an experience similar to cross-site publishing.  In fact, the content search web part could be re-written for delivery through the app model as an “App Part” for SharePoint Online. 
Although the app model provides great flexibility and reuse, it does come with some drawbacks.  Because an app part is delivered through a glorified IFRAME, it would be challenging to navigate to a new page from within the app part.  A link within the app would only navigate within the IFRAME (not the parent of the IFRAME).  Secondly, there isn’t a great mechanism for templating a site to automatically leverage an app part on its page(s).  Apps do not work with site templates, so a site that contains an app cannot be saved as a template.  Apps can be “stapled” to sites, but the app installed event (which would be needed to add the app part to a page) only fires when the app is installed into the app catalog.

REST APIs and Script Editor

The script editor web part is a powerful new tool that can help deliver flexible customization into SharePoint Online.  The script editor web part allows a block of client-side script to be added to any wiki or web part page in a site.  Combined with the new SharePoint REST APIs, the script editor web part can deliver mash-ups very similar to cross-site publishing and the content search web part.  Unlike apps for SharePoint, the script editor isn’t constrained by IFRAME containers, app permissions, or templating limitations.  In fact, a well-configured script editor web part could be exported and re-imported into the web part gallery for reuse.

Cross-site publishing leverages “catalogs” for precise querying of specific content.  Any List/Library can be designated as a catalog.  By making this designation, SharePoint will automatically create managed properties for columns of the List/Library and ultimately generate a search result source in sites that consume the catalog.  Although SharePoint Online doesn’t support catalogs, it support the building blocks such as managed properties and result sources.  These can be manually configured to provide the same precise querying in SharePoint Online and exploited in the script editor web part for display.

Calling Search REST APIs

<div id=”divContentContainer”></div> <script type=”text/javascript”>     $(document).ready(function ($) {         var basePath = “https://tenant.sharepoint.com/sites/somesite/_api/&#8221;;         $.ajax({             url: basePath + “search/query?Querytext=’ContentType:News'”,             type: “GET”,             headers: { “Accept”: “application/json;odata=verbose” },             success: function (data) {                 //script to build UI HERE             },             error: function (data) {                 //output error HERE             }         });     }); </script>

 

An easier approach might be to directly reference a list/library in the REST call of our client-side script.  This wouldn’t require manual search configuration and would provide real-time publishing (no waiting for new items to get indexed).  You could think of this approach similar to a content by query web part across site collections (possibly even farms) and the REST API makes it all possible!

List REST APIs

<div id=”divContentContainer”></div> <script type=”text/javascript”>     $(document).ready(function ($) {         var basePath = “https://tenant.sharepoint.com/sites/somesite/_api/&#8221;;         $.ajax({             url: basePath + “web/lists/GetByTitle(‘News’)/items/?$select=Title&$filter=Feature eq 0”,             type: “GET”,             headers: { “Accept”: “application/json;odata=verbose” },             success: function (data) {                 //script to build UI HERE             },             error: function (data) {                 //output error HERE             }         });     }); </script>

 

The content search web part uses display templates to render search results in different arrangements (ex: list with images, image carousel, etc).  There are two types of display templates the content search web part leverages…the control template, which renders the container around the items, and the item template, which renders each individual item in the search results.  This is very similar to the way a Repeater control works in ASP.NET.  Display templates are authored using HTML, but are converted to client-side script automatically by SharePoint for rendering.  I mention this because our approach is very similar…we will leverage a container and then loop through and render items in script.  In fact, all the examples in this post were converted from display templates in a public site I’m working on. 

Item display template for content search web part

<!–#_ var encodedId = $htmlEncode(ctx.ClientControl.get_nextUniqueId() + “_ImageTitle_”); var rem = index % 3; var even = true; if (rem == 1)     even = false; var pictureURL = $getItemValue(ctx, “Picture URL”); var pictureId = encodedId + “picture”; var pictureMarkup = Srch.ContentBySearch.getPictureMarkup(pictureURL, 140, 90, ctx.CurrentItem, “mtcImg140”, line1, pictureId); var pictureLinkId = encodedId + “pictureLink”; var pictureContainerId = encodedId + “pictureContainer”; var dataContainerId = encodedId + “dataContainer”; var dataContainerOverlayId = encodedId + “dataContainerOverlay”; var line1LinkId = encodedId + “line1Link”; var line1Id = encodedId + “line1”;  _#–> <div style=”width: 320px; float: left; display: table; margin-bottom: 10px; margin-top: 5px;”>    <a href=”_#= linkURL =#_”>       <div style=”float: left; width: 140px; padding-right: 10px;”>          <img src=”_#= pictureURL =#_” class=”mtcImg140″ style=”width: 140px;” />       </div>       <div style=”float: left; width: 170px”>          <div class=”mtcProfileHeader mtcProfileHeaderP”>_#= line1 =#_</div>       </div>    </a> </div>

 

Script equivalent

<div id=”divUnfeaturedNews”></div> <script type=”text/javascript”>     $(document).ready(function ($) {         var basePath = “https://richdizzcom.sharepoint.com/sites/dallasmtcauth/_api/&#8221;;         $.ajax({             url: basePath + “web/lists/GetByTitle(‘News’)/items/?$select=Title&$filter=Feature eq 0”,             type: “GET”,             headers: { “Accept”: “application/json;odata=verbose” },             success: function (data) {                 //get the details for each item                 var listData = data.d.results;                 var itemCount = listData.length;                 var processedCount = 0;                 var ul = $(“<ul style=’list-style-type: none; padding-left: 0px;’ class=’cbs-List’>”);                 for (i = 0; i < listData.length; i++) {                     $.ajax({                         url: listData[i].__metadata[“uri”] + “/FieldValuesAsHtml”,                         type: “GET”,                         headers: { “Accept”: “application/json;odata=verbose” },                         success: function (data) {                             processedCount++;                             var htmlStr = “<li style=’display: inline;’><div style=’width: 320px; float: left; display: table; margin-bottom: 10px; margin-top: 5px;’>”;                             htmlStr += “<a href=’#’>”;                             htmlStr += “<div style=’float: left; width: 140px; padding-right: 10px;’>”;                             htmlStr += setImageWidth(data.d.PublishingRollupImage, ‘140’);                             htmlStr += “</div>”;                             htmlStr += “<div style=’float: left; width: 170px’>”;                             htmlStr += “<div class=’mtcProfileHeader mtcProfileHeaderP’>” + data.d.Title + “</div>”;                             htmlStr += “</div></a></div></li>”;                             ul.append($(htmlStr))                             if (processedCount == itemCount) {                                 $(“#divUnfeaturedNews”).append(ul);                             }                         },                         error: function (data) {                             alert(data.statusText);                         }                     });                 }             },             error: function (data) {                 alert(data.statusText);             }         });     });     function setImageWidth(imgString, width) {         var img = $(imgString);         img.css(‘width’, width);         return img[0].outerHTML;     } </script>

 

Even one of the more complex carousel views from my site took less than 30min to convert to the script editor approach.

Advanced carousel script

<div id=”divFeaturedNews”>     <div class=”mtc-Slideshow” id=”divSlideShow” style=”width: 610px;”>         <div style=”width: 100%; float: left;”>             <div id=”divSlideShowSection”>                 <div style=”width: 100%;”>                     <div class=”mtc-SlideshowItems” id=”divSlideShowSectionContainer” style=”width: 610px; height: 275px; float: left; border-style: none; overflow: hidden; position: relative;”>                         <div id=”divFeaturedNewsItemContainer”>                         </div>                     </div>                 </div>             </div>         </div>     </div> </div> <script type=”text/javascript”>     $(document).ready(function ($) {         var basePath = “https://richdizzcom.sharepoint.com/sites/dallasmtcauth/_api/&#8221;;         $.ajax({             url: basePath + “web/lists/GetByTitle(‘News’)/items/?$select=Title&$filter=Feature eq 1&$top=4”,             type: “GET”,             headers: { “Accept”: “application/json;odata=verbose” },             success: function (data) {                 var listData = data.d.results;                 for (i = 0; i < listData.length; i++) {                     getItemDetails(listData, i, listData.length);                 }             },             error: function (data) {                 alert(data.statusText);             }         });     });     var processCount = 0;     function getItemDetails(listData, i, count) {         $.ajax({             url: listData[i].__metadata[“uri”] + “/FieldValuesAsHtml”,             type: “GET”,             headers: { “Accept”: “application/json;odata=verbose” },             success: function (data) {                 processCount++;                 var itemHtml = “<div class=’mtcItems’ id=’divPic_” + i + “‘ style=’width: 610px; height: 275px; float: left; position: absolute; border-bottom: 1px dotted #ababab; z-index: 1; left: 0px;’>”                 itemHtml += “<div id=’container_” + i + “‘ style=’width: 610px; height: 275px; float: left;’>”;                 itemHtml += “<a href=’#’ title='” + data.d.Caption_x005f_x0020_x005f_Title + “‘ style=’width: 610px; height: 275px;’>”;                 itemHtml += data.d.Feature_x005f_x0020_x005f_Image;                 itemHtml += “</a></div></div>”;                 itemHtml += “<div class=’titleContainerClass’ id=’divTitle_” + i + “‘ data-originalidx='” + i + “‘ data-currentidx='” + i + “‘ style=’height: 25px; z-index: 2; position: absolute; background-color: rgba(255, 255, 255, 0.8); cursor: pointer; padding-right: 10px; margin: 0px; padding-left: 10px; margin-top: 4px; color: #000; font-size: 18px;’ onclick=’changeSlide(this);’>”;                 itemHtml += data.d.Caption_x005f_x0020_x005f_Title;                 itemHtml += “<span id=’currentSpan_” + i + “‘ style=’display: none; font-size: 16px;’>” + data.d.Caption_x005f_x0020_x005f_Body + “</span></div>”;                 $(‘#divFeaturedNewsItemContainer’).append(itemHtml);                 if (processCount == count) {                     allItemsLoaded();                 }             },             error: function (data) {                 alert(data.statusText);             }         });     }     window.mtc_init = function (controlDiv) {         var slideItems = controlDiv.children;         for (var i = 0; i < slideItems.length; i++) {             if (i > 0) {                 slideItems[i].style.left = ‘610px’;             }         };     };     function allItemsLoaded() {         var slideshows = document.querySelectorAll(“.mtc-SlideshowItems”);         for (var i = 0; i < slideshows.length; i++) {             mtc_init(slideshows[i].children[0]);         }         var div = $(‘#divTitle_0’);         cssTitle(div, true);         var top = 160;         for (i = 1; i < 4; i++) {             var divx = $(‘#divTitle_’ + i);             cssTitle(divx, false);             divx.css(‘top’, top);             top += 35;         }     }     function cssTitle(div, selected) {         if (selected) {             div.css(‘height’, ‘auto’);             div.css(‘width’, ‘300px’);             div.css(‘top’, ’10px’);             div.css(‘left’, ‘0px’);             div.css(‘font-size’, ’26px’);             div.css(‘padding-top’, ‘5px’);             div.css(‘padding-bottom’, ‘5px’);             div.find(‘span’).css(‘display’, ‘block’);         }         else {             div.css(‘height’, ’25px’);             div.css(‘width’, ‘auto’);             div.css(‘left’, ‘0px’);             div.css(‘font-size’, ’18px’);             div.css(‘padding-top’, ‘0px’);             div.css(‘padding-bottom’, ‘0px’);             div.find(‘span’).css(‘display’, ‘none’);         }     }     window.changeSlide = function (item) {         //get all title containers         var listItems = document.querySelectorAll(‘.titleContainerClass’);         var currentIndexVals = { 0: null, 1: null, 2: null, 3: null };         var newIndexVals = { 0: null, 1: null, 2: null, 3: null };         for (var i = 0; i < listItems.length; i++) {             //current Index             currentIndexVals[i] = parseInt(listItems[i].getAttribute(‘data-currentidx’));         }         var selectedIndex = 0; //selected Index will always be 0         var leftOffset = ”;         var originalSelectedIndex = ”;         var nextSelected = ”;         var originalNextIndex = ”;         if (item == null) {             var item0 = document.querySelector(‘[data-currentidx=”‘ + currentIndexVals[0] + ‘”]’);             originalSelectedIndex = parseInt(item0.getAttribute(‘data-originalidx’));             originalNextIndex = originalSelectedIndex + 1;             nextSelected = currentIndexVals[0] + 1;         }         else {             nextSelected = item.getAttribute(‘data-currentidx’);             originalNextIndex = item.getAttribute(‘data-originalidx’);         }         if (nextSelected == 0) { return; }         for (i = 0; i < listItems.length; i++) {             if (currentIndexVals[i] == selectedIndex) {                 //this is the selected item, so move to bottom and animate                 var div = $(‘[data-currentidx=”0″]’);                 cssTitle(div, false);                 div.css(‘left’, ‘-400px’);                 div.css(‘top’, ‘230px’);                 newIndexVals[i] = 3;                 var item0 = document.querySelector(‘[data-currentidx=”0″]’);                 originalSelectedIndex = item0.getAttribute(‘data-originalidx’);                 //annimate                 div.delay(500).animate(                     { left: ‘0px’ }, 500, function () {                     });             }             else if (currentIndexVals[i] == nextSelected) {                 //this is the NEW selected item, so resize and slide in as selected                 var div = $(‘[data-currentidx=”‘ + nextSelected + ‘”]’);                 cssTitle(div, true);                 div.css(‘left’, ‘-610px’);                 newIndexVals[i] = 0;                 //annimate                 div.delay(500).animate(                     { left: ‘0px’ }, 500, function () {                     });             }             else {                 //move up in queue                 var curIdx = currentIndexVals[i];                 var div = $(‘[data-currentidx=”‘ + curIdx + ‘”]’);                 var topStr = div.css(‘top’);                 var topInt = parseInt(topStr.substring(0, topStr.length – 1));                 if (curIdx != 1 && nextSelected == 1 || curIdx > nextSelected) {                     topInt = topInt – 35;                     if (curIdx – 1 == 2) { newIndexVals[i] = 2 };                     if (curIdx – 1 == 1) { newIndexVals[i] = 1 };                 }                 //move up                 div.animate(                     { top: topInt }, 500, function () {                     });             }         };         if (originalNextIndex < 0)             originalNextIndex = itemCount – 1;         //adjust pictures         $(‘#divPic_’ + originalNextIndex).css(‘left’, ‘610px’);         leftOffset = ‘-610px’;         $(‘#divPic_’ + originalSelectedIndex).animate(             { left: leftOffset }, 500, function () {             });         $(‘#divPic_’ + originalNextIndex).animate(             { left: ‘0px’ }, 500, function () {             });         var item0 = document.querySelector(‘[data-currentidx=”‘ + currentIndexVals[0] + ‘”]’);         var item1 = document.querySelector(‘[data-currentidx=”‘ + currentIndexVals[1] + ‘”]’);         var item2 = document.querySelector(‘[data-currentidx=”‘ + currentIndexVals[2] + ‘”]’);         var item3 = document.querySelector(‘[data-currentidx=”‘ + currentIndexVals[3] + ‘”]’);         if (newIndexVals[0] != null) { item0.setAttribute(‘data-currentidx’, newIndexVals[0]) };         if (newIndexVals[1] != null) { item1.setAttribute(‘data-currentidx’, newIndexVals[1]) };         if (newIndexVals[2] != null) { item2.setAttribute(‘data-currentidx’, newIndexVals[2]) };         if (newIndexVals[3] != null) { item3.setAttribute(‘data-currentidx’, newIndexVals[3]) };     }; </script>

 

End-result of script editors in SharePoint Online

Separate authoring site collection

Final Thoughts

How To : Use Git Tools for TFS Integration

Git – TFS Integration – Why it matters

 

For many small development shops, the idea of using TFS and a centralized source control repository is anathema. The mere thought of being restricted by a software configuration manager on how and when to branch or merge cuts against everything they cherish in software development.

 

Git is their natural and chosen ground for managing source code. The freedom and flexibility of using Git enables them to work where they are. This is especially true if they are working as part of a distributed team on modular projects.

Microsoft addressed many of the existing concerns with TFS source control with the advent of TFS 2012 and local workspaces. However, even though local workspaces enable great flexibility in offline work, they are still ultimately tied to a central repository and the policies and restrictions imposed on it.

 

Enter Git support in TFS. Git support currently comes in two forms; stand alone Git support in Visual Studio and Git support with TFS.

Git support with Visual Studio is completely straightforward. Simply change the source control plug-in selection to the Microsoft Git Provider and all the power and flexibility of Git is available to the Visual Studio developer such as private branches and online collaboration with Git hosts such as GitHub and BitBucket.

Configuring Git for Visual Studio Source Control

However, from an ALM perspective, the real power and the compelling feature of Microsoft’s integration with Git is the ability to work with TFS.

 

Developers still get all the advantages and flexibility of Git, but can also take advantage of the ALM features of TFS such as work item tracking, team tools and integrated build. The Git – TFS integration gets us much closer to the ultimate goal of true cross-platform support in a single ALM toolset.

 

The TFS – Git integration can be utilized a couple of ways. The first option is the ability to essentially synchronize a Git repository with TFS source control with the Git-TF utility. This utility makes it easy to clone sources from TFS, fetch updates from TFS and push changes back to TFS.

 

What’s more, it fully supports TFS shelvesets and work item integration, which presents some exciting possibilities. The features and functionality Git-TF provides makes it a compelling solution and a credible compromise between centrally managed teams with source control and distributed teams with distributed source control.

The second option, available now only through Microsoft’s hosted TFS Service, is the ability for organizations to create TFS Team Projects with Git hosted source control (this ability is reportedly planned for on premise TFS support in the next release). This is a fairly exciting development.

 

Having the choice between native TFS version control and Git when creating a team project opens many doors that hitherto were locked shut.

XCode IDE connected to a TFS hosted repository

Eclipse, XCode, Visual Studio and any other IDE that supports Git can now be used to leverage the powerful ALM features TFS provides.

As an ALM consultant, that’s the part that excites me the most. Hosting all development efforts in a single environment; an environment that supports all the various technologies in play and being able to track and manage those efforts with agility and transparency is a huge benefit to any organization that provides multiple platform solutions.

 

Even those who don’t, will now have the option to at least evaluate the feasibility of utilizing TFS in development environments not typically associated with a Microsoft project.

The mythical promised land of cross-platform ALM may have just become quite less mythical.

 

———————Microsoft’s Tool for Git and TFS Integration – ———————————————————————–

 http://gittf.codeplex.com

Working with Teams

The Git-TF tool is most easily used by a single developer or multiple developers working independently with their own isolated Git repos. That is, each developer uses Git-TF to clone a local repo where they can then use Git to manage their local development that will eventually be checked in to TFS. In this “hub and spoke” configuration, all code is shared through TFS at the “hub” and each developer using Git becomes a “spoke”. Developers looking to collaborate using Git’s distributed sharing capabilities will want to work in a specific configuration described below.

Most often, developers collaborating with Git have cloned from a common repo. When it comes time to share divergent changes, conflict resolution is easy because each repository shares the same common base version. Many times, conflicts are automatically resolved. One of the keys to this merging of histories is that each commit is assigned a unique identifier that is generated by the contents of the commit. When working with Git-TF, two repositories cloned from the same TFS path will not have the same commit IDs unless the clones were done at the same point in TFS history, and with the same depth. In the event that two Git repos that were independently cloned using Git-TF share changes directly, the result will be a baseless merge of the repositories and a large number of conflicts. For this reason, it is not recommended that teams using Git-TF ever share changes directly through Git (i.e. using git push and git pull).

Instead, it is recommended that a team working with Git-TF and collaborating with Git do so by designating a single repo as the point of contact with TFS. This configuration may look as follows for a team of three developers:

          [TFS]      [Shared Git repo]
            |         ^ (2)  |       \
            |        /       |        \
            |       /        |         \
            V (1)  /         V (3)      V (4)
       [Alice's Repo]   [Bob's Repo]   [Charlie's Repo]
 

In the configuration above the actions would be as follows:

1. Using the git tf clone command, Alice clones a path from TFS into a local Git repo.
2. Next, Alice uses git push to push the commit created in her local Git repo into the team’s shared Git repo.
3. Bob can then use git clone to clone down the changes that Alice pushed.
4. Charlie can also use git clone to clone down the changes that Alice pushed.

Both Bob and Charlie only ever interact with the team’s shared Git repo using git push and git pull. They can also interact directly with one another’s repos (or with Alice’s) , but should never use Git-TF commands to interact with TFVC.

When working with the team, Alice will typically develop locally and use git push and git pull to share changes with the team. When the team decides they have changes to share with TFS, Alice will use a git tf checkin to share those changes (typically a git tf checkin –shallow will be used). Likewise, if there are changes that the team needs from TFVC, Alice will perform a git tf pull, using the –merge or –rebase options as appropriate, and then use git push to share the changes with the team.

Note that (until Issue 77 is addressed) all changes coming into the TFVC repository will come in as if from Alice’s TFS identity. This is fine if only Alice has an identity on that TFVC project but it may well not be what you want if Bob and Charlie also had valid identities in that TFS project.

Rebase vs. Merge

Once changes have been fetched from TFS using git tf pull (or git tf fetch), those changes must either be merged with the HEAD or have any changes since the last fetch rebased on top of FETCH_HEAD. Git-TF allows developers to work in either manner, though if the repo that is sharing changes with TFS has shared any commits with other Git users, then this rebase may result in significant conflicts (see The Perils of Rebasing). For this reason, it is recommended that any team working in the aforementioned team configuration use git tf pull with the default –merge option (or use git merge FETCH_HEAD to incorporate changes made in TFS after fetching manually).

Recommended Git Settings

When using the Git-TF tools, there are a few recommended settings that should make it easier to work with other developers that are using TFS.

Line Endings

core.autocrlf = false

Git has a feature to allow line endings to be normalized for a repository, and it provides options for how those line endings should be set when files are checked out. TFS does not have any feature to normalize line endings – it stores exactly what is checked in by the user. When using Git-TF, choosing to normalize line endings to Unix-style line endings (LF) will likely result in TFS users (especially those using VS) changing the line endings back to Windows-style line endings (CRLF). As a result, it is recommended to set the core.autocrlf option to false, which will keep line endings unchanged in the Git repo.

Ignore case

core.ignorecase = true

TFS does not allow multiple files that differ only in case to exist in the same folder at the same time. Git users working on non-Windows machines could commit files to their repo that differ only in case, and attempting to check in those changes to TFS will result in an error. To avoid these types of errors, the core.ignorecase option should be set to true.

How To : Use the REST API and AngularJS to Create a Web Part to retrieve List Items

Introduction

This article explains how to get the data from a SharePoint List using Angular JavaScript and the REST API. I used the REST API to talk to SharePoint and get the data from the list.

In this script we just see that we have first created an Angular Controller with the name “spCustomerController”. We have also injected $scope and $http service.

The $http service will fetch the list data from the specific columns of the SharePoint list. $scope is a glue between a Controller and a View. It acts as execution context for Expressions. Angular expressions are code snippets that are usually placed in bindings such as {{ expression }}.

Use the following procedure to create a sample.

1. <h1>WelCome To Angular JS Sharepoint 2013 REST API !!</h1>  
2.   
3. <div ng-app=“SharePointAngApp” class=“row”>  
4.     <div ng-controller=“spCustomerController” class=“span10”>  
5.         <table class=“table table-condensed table-hover”>  
6.             <tr>  
7.                 <th>Title</th>  
8.                 <th>Employee</th>  
9.                 <th>Company</th>  
10.                  
11.             </tr>  
12.             <tr ng-repeat=“customer in customers”>  
13.                 <td>{{customer.Title}}</td>  
14.                 <td>{{customer.Employee}}</td>  
15.                 <td>{{customer.Company}}</td>  
16.                 </tr>  
17.         </table>  
18.     </div>  
19. </div>  

 

Step 1: Navigate to your SharePoint 2013 site.

Step 2: From this page select the Site Actions | Edit Page.

Edit the page, go to the “Insert” tab in the Ribbon and click the “Web Part” option. In the “Web Parts” picker area, go to the “Media and Content” category, select the “Script Editor” Web Part and press the “Add button”.

Step 3: Once the Web Part is inserted into the page, you will see an “EDIT SNIPPET” link; click it. You can insert the HTML and/or JavaScript as in the following

1. <style>  
2. table, td, th {  
3.     border: 1px solid green;  
4. }  
5.   
6. th {  
7.     background-color: green;  
8.     color: white;  
9. }  
10. </style>  
11. <script src=“https://ajax.googleapis.com/ajax/libs/angularjs/1.0.1/angular.min.js&#8221;></script>  
12. <script src=“http://code.jquery.com/ui/1.10.3/jquery-ui.min.js&#8221;></script>  
13.   
14. <script>  
15.       
16.   
17.     var myAngApp = angular.module(‘SharePointAngApp’, []);  
18.     myAngApp.controller(‘spCustomerController’, function ($scope, $http) {  
19.         $http({  
20.             method: ‘GET’,  
21.             url: _spPageContextInfo.webAbsoluteUrl + “/_api/web/lists/getByTitle(‘InfoList’)/items?$select=Title,Employee,Company”,  
22.             headers: { “Accept”: “application/json;odata=verbose” }  
23.         }).success(function (data, status, headers, config) {  
24.             $scope.customers = data.d.results;  
25.         }).error(function (data, status, headers, config) {  
26.          
27.         });  
28.     });  
29.       
30. </script>  
31.   
32. <h1> Angular JS SharePoint 2013 REST API !!</h1>  
33.   
34. <div ng-app=“SharePointAngApp” class=“row”>  
35.     <div ng-controller=“spCustomerController” class=“span10”>  
36.         <table class=“table table-condensed table-hover”>  
37.             <tr>  
38.                 <th>Title</th>  
39.                 <th>Employee</th>  
40.                 <th>Company</th>  
41.                  
42.             </tr>  
43.             <tr ng-repeat=“customer in customers”>  
44.                 <td>{{customer.Title}}</td>  
45.                 <td>{{customer.Employee}}</td>  
46.                 <td>{{customer.Company}}</td>  
47.                 </tr>  
48.         </table>  
49.     </div>  
50. </div>  

 

Finally the result show look as below:

 

A Look At : The New Search Functionality in SharePoint Online and how Developers can make use of it

http://en.gravatar.com/sharepointsamurai/

 

Search functionality in SharePoint 2013 includes several enhancements, custom content processing and a new framework for presenting search result types. SharePoint Server 2013 presents a new search architecture that includes substantial changes and additions to the search components and databases.

Also, there have been significant enhancements made to the Keyword Query Language (KQL).

Some of the features and functionalities have been depreciated from the previous version of SharePoint 2013. There has been a more search user interface improvement which brings the user more interactive with search results. For example, users can rest the pointer over a search result to see the content preview in the hover panel to the right of the result.

Now you can see Office 365 SharePoint 2013 and its admin features of Search Service Application. It’s a breakthrough advancing; nearly all the new features listed here are missed in Office 365 – SharePoint 2010. The following screen capture shows the SharePoint central administrator view for the Search section.

Manage all aspects of the Search experience for your end users improving the relevancy of your results per your content and metadata.

Search helps users quickly return to important sites and documents by remembering what they have previously searched and clicked. The results of previously searched and clicked items are displayed as query suggestions at the top of the results page.

In addition to the default manner in which search results are differentiated, site collection administrators and site owners can create and use result types to customize how results are displayed for important documents. A result type is a rule that identifies a type of result and a way to display it.

 

Manage Search Schema

Managed properties are used to restrict search results, and present the content of the properties in search results. Crawled properties are automatically extracted from crawled content. All the changes to properties will take effect only after the next full crawl.

Under the search schema section, administrator can:

• View, create, or modify Managed Properties and map crawled properties to managed properties
• View or modify Crawled Properties, or to view crawled properties in a particular category
• View or modify Categories, or view crawled properties in a particular category.

While creating a new managed property, the ‘Mappings to crawled properties’ is one of the key attributes for the configuration set in our new property.

 

 

Manage Search Dictionaries

	Taxonomy Term Store
People	Search Dictionaries	System
Department	Company Exclusions	Hashtags
Job Title	Company Inclusions	Keywords
Location	Query Spelling Exclusions	Orphaned terms
	Query Spelling Includings

 

Manage Authoritative Pages

Search in SharePoint 2013 will analyze the collection of authoritative and non-authoritative pages to determine the ranking of search results. The authoritative sites are of two kinds:

• Authoritative Site Pages
• Non-authoritative Site Pages

Authoritative site pages are the links, which administrator authorized to be the most relevant information. There can be multiple authoritative pages in each environment. There is an option for specifying second and third-level authorities for search ranking. Non-authoritative site pages are the content from certain sites can be ranked lower than the rest of the content in the site.

 

Query Suggestion Settings

SharePoint Search comprises various features that you can leverage for building productivity solutions. One of the interesting and useful competencies are Query Suggestions. The query suggestions are administrated by two options as follows:

• Always Suggest Phrases
• Never Suggest Phrases

Manage Result Sources

Result Sources are used to frame the search results and confederate queries to external sources, such as internet search engines, etc. Once the result source are defined, we can configure search web parts and query rule actions to use the result source.

How the Result Source is managed? A SharePoint Online administrator of SharePoint Online Tenant can manage result sources for all site collections and sites reside under the same tenant. A site collection administrator or a site owner can manage result sources for a site collection or a site, respectively.

SharePoint 2013 provides 16 pre-defined result sources. The pre-configured default result source is Local SharePoint Results. We can state a different result source as the default as per our requirement

.

While creating a new Result Source, there is Protocol and Query transform are the two important parameters which tells the Result Source what to do in the SharePoint.

Protocol – Local SharePoint for results from the index of this Search Service. OpenSearch 1.0/1.1 for results from a search engine that uses that protocol. Exchange for results from an exchange source. Remote SharePoint for results from the index of a search service hosted in another farm.

Query Transform – Change incoming queries to use this new query text instead. Include the incoming query in the new text by using the query variable “{searchTerms}“.

Use this to scope results. For example, to only return OneNote items, set the new text to “{searchTerms} fileextension=one“. Then, an incoming query “sharepoint” becomes “sharepoint fileextension=one“. Launch the Query Builder for additional options.

 

Manage Query Rules

Query rules are to conditionally stimulate the search results and show hunks of supplementary results based on the rules created in the SharePoint. In a query rule, you can specify conditions and correlated actions without any help of code. The user with Site Collection, Site owner permission level can create and manage the query rules.

 

Manage Query Client Types

Query Client Types are one of the new search features in SharePoint 2013. Client Type identifies an application where a search query is sent from. Applications are prioritized by tiers. Top tier has the highest priority. When resource limit is reached, query throttling becomes ON, and search system will process the queries from top tier to bottom tier.

System Client Types are available out-of-the box, and cannot be deleted. We can add a new custom Client Type by clicking on New Client Type.

 

Remove Search Results

To remove data from the search results, type the URLs which needed to remove from it. All the URLs listed in the textbox will be removed from search results immediately, once after the Remove Now button is clicked.

View Usage Reports

Here the administrator will be able to see the usage reports and search related report, example Query Rules usage by day, Top Queries by Day, etc.

Search Center Settings

In this setting, the default search system will be mapped. Usually the Enterprise Search Center site that has been created for search entire SharePoint sites in the organization.

Export Search Configuration

Create a file that includes all customized query rules, result sources, result types, ranking models and site search settings but not any that shipped with SharePoint, in the current tenant that can be imported to other tenants.

Import Search Configuration

If you have a search configuration you’d like to import, browse for it below. Settings imported from the file will be created and activated as part of the site. You can modify any of the settings after import.

Crawl Log Permissions

Grant users read access to crawl log information for this tenant.

Search Client Object Model

SharePoint 2013 Search includes a client object model (CSOM) that enables access to most of the Query object model functionality for online, on-premises, and mobile development. You can use the Search CSOM to create client applications that run on a machine that does not have SharePoint 2013 installed to return SharePoint 2013 Preview search results.

The Search CSOM includes a Microsoft .NET Framework managed client object model and JavaScript object model, and it is built on SharePoint 2013. First, client code accesses the SharePoint CSOM. Then, client code accesses the Search CSOM.

NOTE: Custom search solutions in SharePoint Server 2013 do not support SQL syntax. Search in SharePoint 2013 supports FQL syntax and KQL syntax for custom search solutions.

We can configure crawled and managed properties. Configure Result Sources which were Federated Result / Scopes in SharePoint Search 2010.

 

Introduction to Business Connectivity Services (BCS)

BCS has the ability to connect and query the data sources and returns the results to the user through an external list, or app for SharePoint, or Office 2013. The Microsoft Office 2013 and SharePoint 2013 include Microsoft Business Connectivity Services (BCS).

The SharePoint 2013 and the Office 2013 suites include Microsoft Business Connectivity Services. With Business Connectivity Services, you can use SharePoint 2013 and Office 2013 clients as an interface into data that doesn’t live in SharePoint 2013 itself. It does this by making a connection to the data source, running a query, and returning the results.

Business Connectivity Services returns the results to the user through an external list, or app for SharePoint, or Office 2013 where you can perform different operations against them, such as Create, Read, Update, Delete, and Query (CRUDQ). Business Connectivity Services can access external data sources through Open Data (OData), Windows Communication Foundation (WCF) endpoints, web services, cloud-based services, and .NET assemblies, or through custom connectors.

Business Connectivity Services can access external data sources through Open Data (OData), Windows Communication Foundation (WCF) endpoints, web services, cloud-based services, and .NET assemblies, or through custom connectors. The Open Data Protocol is known as OData. It is an open web protocol for querying and updating data.

Business Connectivity Services uses SharePoint 2013 and Office 2013 as a client interface for data which doesn’t reside SharePoint 2013 environment.

The following screen capture is the BCS features and configuration options available under the SharePoint Administration Center in the Office 365.

How To : Use JavaScript: Error Handling to Build More Efficient Windows Store Apps

Believe it or not, sometimes app developers write code that doesn’t work. Or the code works but is terribly inefficient and hogs memory. Worse yet, inefficient code results in a poor UX, driving users crazy and compelling them to uninstall the app and leave bad reviews.

I’m going to explore common performance and efficiency problems you might encounter while building Windows Store apps with JavaScript. In this article, I take a look at best practices for error handling using the Windows Library for JavaScript (WinJS). In a future article, I’ll discuss techniques for doing work without blocking the UI thread, specifically using Web Workers or the new WinJS.Utilities.Scheduler API in WinJS 2.0, as found in Windows 8.1. I’ll also present the new predictable-object lifecycle model in WinJS 2.0, focusing particularly on when and how to dispose of controls.

For each subject area, I focus on three things:

• Errors or inefficiencies that might arise in a Windows Store app built using JavaScript.
• Diagnostic tools for finding those errors and inefficiencies.
• WinJS APIs, features and best practices that can ameliorate specific problems.

I provide some purposefully buggy code but, rest assured, I indicate in the code that something is or isn’t supposed to work.

I use Visual Studio 2013, Windows 8.1 and WinJS 2.0 for these demonstrations. Many of the diagnostic tools I use are provided in Visual Studio 2013. If you haven’t downloaded the most-recent versions of the tools, you can get them from the Windows Dev Center (bit.ly/K8nkk1). New diagnostic tools are released through Visual Studio updates, so be sure to check for updates periodically.

I assume significant familiarity with building Windows Store apps using JavaScript. If you’re relatively new to the platform, I suggest beginning with the basic “Hello World” example (bit.ly/vVbVHC) or, for more of a challenge, the Hilo sample for JavaScript (bit.ly/SgI0AA).

Setting up the Example

First, I create a new project in Visual Studio 2013 using the Navigation App template, which provides a good starting point for a basic multipage app. I also add a NavBar control (bit.ly/14vfvih) to the default.html page at the root of the solution, replacing the AppBar code the template provided. Because I want to demonstrate multiple concepts, diagnostic tools and programming techniques, I’ll add a new page to the app for each demonstration. This makes it much easier for me to navigate between all the test cases.

The complete HTML markup for the NavBar is shown in Figure 1. Copy and paste this code into your solution if you’re following along with the example.

Figure 1 The NavBar Control

<!-- The global navigation bar for the app. -->
<div id="navBar" data-win-control="WinJS.UI.NavBar">
  <div id="navContainer" 
       data-win-control="WinJS.UI.NavBarContainer">
    <div id="homeNav" 
      data-win-control="WinJS.UI.NavBarCommand"
      data-win-options="{
        location: '/pages/home/home.html',
        icon: 'home',
        label: 'Home page'
    }">
    </div>
    <div id="handlingErrors"
      data-win-control="WinJS.UI.NavBarCommand"
      data-win-options="{
        location: '/pages/handlingErrors/handlingErrors.html',
        icon: 'help',
        label: 'Handling errors'
    }">
    </div>
    <div id="chainedAsync"
      data-win-control="WinJS.UI.NavBarCommand"
      data-win-options="{
        location: '/pages/chainedAsync/chainedAsync.html',
        icon: 'link',
        label: 'Chained asynchronous calls'
    }">
    </div>
  </div>
</div>

For more information about building a navigation bar, check out some of the Modern Apps columns by Rachel Appel, such as the one at msdn.microsoft.com/magazine/dn342878.

You can run this project with just the navigation bar, except that clicking any of the navigation buttons will raise an exception in navigator.js. Later in this article, I’ll discuss how to handle errors that come up in navigator.js. For now, remember the app always starts on the home­page and you need to right-click the app to bring up the navigation bar.

Handling Errors

Obviously, the best way to avoid errors is to release apps that don’t raise errors. In a perfect world, every developer would write perfect code that never crashes and never raises an exception. That perfect world doesn’t exist.

As much as users prefer apps that are completely error-free, they are exceptionally good at finding new and creative ways to break apps—ways you never dreamed of. As a result, you need to incorporate robust error handling into your apps.

Errors in Windows Store apps built with JavaScript and HTML act just like errors in normal Web pages. When an error happens in a Document Object Model (DOM) object that allows for error handling (for example, the <script>, <style> or <img> elements), the onerror event for that element is raised. For errors in the JavaScript call stack, the error travels up the chain of calls until caught (in a try/catch block, for instance) or until it reaches the window object, raising the window.onerror event.

WinJS provides several layers of error-handling opportunities for your code in addition to what’s already provided to normal Web pages by the Microsoft Web Platform. At a fundamental level, any error not trapped in a try/catch block or the onError handler applied to a WinJS.Promise object (in a call to the then or done methods, for example) raises the WinJS.Application.onerror event. I’ll examine that shortly.

In practice, you can listen for errors at other levels in addition to Application.onerror. With WinJS and the templates provided by Visual Studio, you can also handle errors at the page-control level and at the navigation level. When an error is raised while the app is navigating to and loading a page, the error triggers the navigation-level error handling, then the page-level error handling, and finally the application-level error handling. You can cancel the error at the navigation level, but any event handlers applied to the page error handler will still be raised.

In this article, I’ll take a look at each layer of error handling, starting with the most important: the Application.onerror event.

Application-Level Error Handling

WinJS provides the WinJS.Application.onerror event (bit.ly/1cOctjC), your app’s most basic line of defense against errors. It picks up all errors caught by window.onerror.” It also catches promises that error out and any errors that occur in the process of managing app model events. Although you can apply an event handler to the window.onerror event in your app, you’re better off just using Application.onerror for a single queue of events to monitor.

Once the Application.onerror handler catches an error, you need to decide how to address it. There are several options:

• For critical blocking errors, alert the user with a message dialog. A critical error is one that affects continued operation of the app and might require user input to proceed.
• For informational and non-blocking errors (such as a failure to sync or obtain online data), alert the user with a flyout or an inline message.
• For errors that don’t affect the UX, silently swallow the error.
• In most cases, write the error to a tracelog (especially one that’s hooked up to an analytics engine) so you can acquire customer telemetry. For available analytics SDKs, visit the Windows services directory at services.windowsstore.com and click on Analytics (under “By service type”) in the list on the left.

For this example, I’ll stick with message dialogs. I open up default.js (/js/default.js) and add the code shown in Figure 2 inside the main anonymous function, below the handler for the app.oncheckpoint event.

Figure 2 Adding a Message Dialog

app.onerror = function (err) {
  var message = err.detail.errorMessage ||
    (err.detail.exception && err.detail.exception.message) ||
    "Indeterminate error";
  if (Windows.UI.Popups.MessageDialog) {
    var messageDialog =
      new Windows.UI.Popups.MessageDialog(
        message,
        "Something bad happened ...");
    messageDialog.showAsync();
    return true;
  }
}

In this example, the error event handler shows a message telling the user an error has occurred and what the error is. The event handler returns true to keep the message dialog open until the user dismisses it. (Returning true also informs the WWAHost.exe process that the error has been handled and it can continue.)

Senior C# & SharePoint Developer with 10 year’s development experience

BSC degree in Computer Science and Information Systems

5 years experience in delivering SharePoint based solutions using OOB functionality and Custom Development

Extensive experience in
• Microsoft SharePoint platform, App Model (2010 & 2013)
• C# 2.0 – 4.5
• Advanced Workflow (Visual Studio, K2, Nintex)
• Development of Custom Web Parts
• Master Page Dev & Branding
• Integration of Back-end systems, including 3 SAP Projects, MS CRM, K2 BlackPearl,
Custom LOB Systems
• SQL Server (design,development, stored procedures, triggers)
• BCS, BDC – Implementing WCF, REST Services, Web Services
• SharePoint Excel Services, PowerPivot, Word Automation Services
• Custom Reports (MS SQL Reporting, Crystal Reports)
• Objected Oriented Programming and Patterns
• TFS 2010-2013
• Agile & SCRUM methodologies (ALM / SDLC)
• Microsoft Azure as database and hosting hybrid solutions
• Office 365 and SharePoint App Development

 

Now I’ll create some errors for this code to handle. I’ll create a custom error, throw the error and then catch it in the event handler. For this first example, I add a new folder named handling­Errors to the pages folder. In the folder, I add a new Page Control by right-clicking the project in Solution Explorer and selecting Add | New Item. When I add the handlingErrors Page Control to my project, Visual Studio provides three files in the handlingErrors folder (/pages/handlingErrors): handlingErrors.html, handling­Errors.js and handlingErrors.css.

I open up handlingErrors.html and add this simple markup inside the <section> tag of the body:

<!-- When clicked, this button raises a custom error. -->
<button id="throwError">Throw an error!</button>

Next, I open handlingErrors.js and add an event handler to the button in the ready method of the PageControl object, as shown in Figure 3. I’ve provided the entire PageControl definition in handlingErrors.js for context.

Figure 3 Definition of the handlingErrors PageControl

// For an introduction to the Page Control template, see the following documentation:
// http://go.microsoft.com/fwlink/?LinkId=232511
(function () {
  "use strict";
  WinJS.UI.Pages.define("/pages/handlingErrors/handlingErrors.html", {
    ready: function (element, options) {
      // ERROR: This code raises a custom error.
      throwError.addEventListener("click", function () {
        var newError = new WinJS.ErrorFromName("Custom error", 
          "I'm an error!");
        throw newError;
      });
    },
    unload: function () {
      // Respond to navigations away from this page.
      },
    updateLayout: function (element) {
      // Respond to changes in layout.
    }
  });
})();

Now I press F5 to run the sample, navigate to the handling­Errors page and click the “Throw an error!” button. (If you’re following along, you’ll see a dialog box from Visual Studio informing you an error has been raised. Click Continue to keep the sample running.) A message dialog then pops up with the error, as shown in Figure 4.

Figure 4 The Custom Error Displayed in a Message Dialog

Custom Errors

The Application.onerror event has some expectations about the errors it handles. The best way to create a custom error is to use the WinJS.ErrorFromName object (bit.ly/1gDESJC). The object created exposes a standard interface for error handlers to parse.

To create your own custom error without using the ErrorFromName object, you need to implement a toString method that returns the message of the error.

Otherwise, when your custom error is raised, both the Visual Studio debugger and the message dialog show “[Object object].” They each call the toString method for the object, but because no such method is defined in the immediate object, it goes through the chain of prototype inheritance for a definition of toString. When it reaches the Object primitive type that does have a toString method, it calls that method (which just displays information about the object).

Page-Level Error Handling

The PageControl object in WinJS provides another layer of error handling for an app. WinJS will call the IPageControlMembers.error method when an error occurs while loading the page. After the page has loaded, however, the IPageControlMembers.error method errors are picked up by the Application.onerror event handler, ignoring the page’s error method.

I’ll add an error method to the PageControl that represents the handleErrors page. The error method writes to the JavaScript console in Visual Studio using WinJS.log. The logging functionality needs to be started up first, so I need to call WinJS.Utilities.startLog before I attempt to use that method. Also note that I check for the existence of the WinJS.log member before I actually call it.

The complete code for handleErrors.js (/pages/handleErrors/handleErrors.js) is shown in Figure 5.

Figure 5 The Complete handleErrors.js

(function () {
  "use strict";
  WinJS.UI.Pages.define("/pages/handlingErrors/handlingErrors.html", {
    ready: function (element, options) {
      // ERROR: This code raises a custom error.      
      throwError.addEventListener("click", function () {
        var newError = {
          message: "I'm an error!",
          toString: function () {
            return this.message;
          }
        };
        throw newError;
      })
    },
    error: function (err) {
      WinJS.Utilities.startLog({ type: "pageError", tags: "Page" });
      WinJS.log && WinJS.log(err.message, "Page", "pageError");
    },
    unload: function () {
      // TODO: Respond to navigations away from this page.
    },
    updateLayout: function (element) {
      // TODO: Respond to changes in layout.
    }
  });
})();

WinJS.log

The call to WinJS.Utilities.startLog shown in Figure 5 starts the WinJS.log helper function, which writes output to the JavaScript console by default. While this helps greatly during design time for debugging, it doesn’t allow you to capture error data after users have installed the app.

For apps that are ready to be published and deployed, you should consider creating your own implementation of WinJS.log that calls into an analytics engine. This allows you to collect telemetry data about your app’s performance so you can fix unforeseen bugs in future versions of your app. Just make sure customers are aware of the data collection and that you clearly list what data gets collected by the analytics engine in your app’s privacy statement.

Note that when you overwrite WinJS.log in this way, the WinJS.log function will catch all output that would otherwise go to the JavaScript console, including things like status updates from the Scheduler. This is why you need to pass a meaningful name and type value into the call to WinJS.Utilities.startLog so you can filter out any errors you don’t want.

Now I’ll try running the sample and clicking “Throw an error!” again. This results in the exact same behavior as before: Visual Studio picks up the error and then the Application.onerror event fires. The JavaScript console doesn’t show any messages related to the error because the error was raised after the page loaded. Thus, the error was picked up only by the Application.onerror event handler.

So why use the PageControl error handling? Well, it’s particularly helpful for catching and diagnosing errors in WinJS controls that are created declaratively in the HTML. For example, I’ll add the following HTML markup inside the <section> tags of handleErrors.html (/pages/handleErrors/handleErrors.html), below the button:

<!-- ERROR: AppBarCommands must be button elements by default
  unless specified otherwise by the 'type' property. -->
<div data-win-control="WinJS.UI.AppBarCommand"></div>

Now I press F5 to run the sample and navigate to the handleErrors page. Again, the message dialog appears until dismissed. However, the following message appears in the JavaScript console (you’ll need to switch back to the desktop to check this):

pageError: Page: Invalid argument: For a button, toggle, or flyout   command, the element must be null or a button element

Note that the app-level error handling appeared even though I handled the error in the PageControl (which logged the error). So how can I trap an error on a page without having it bubble up to the application?

The best way to trap a page-level error is to add error handling to the navigation code. I’ll demonstrate that next.

Navigation-Level Error Handling

When I ran the previous test where the app.on­error event handler handled the page-level error, the app seemed to stay on the homepage. Yet, for some reason, a Back button control appeared. When I clicked the Back button, it took me to a (disabled) handlingErrors.html page.

This is because the navigation code in navigator.js (/js/navigator.js), which is provided in the Navigation App project template, still attempts to navigate to the page even though the page has fizzled. Furthermore, it navigates back to the homepage and adds the error-prone page to the navigation history. That’s why I see the Back button on the homepage after I’ve attempted to navigate to handlingErrors.html.

To cancel the error in navigator.js, I replace the PageControl­Navigator._navigating function with the code in Figure 6. You see that the navigating function contains a call to WinJS.UI.Pages.render, which returns a Promise object. The render method attempts to create a new PageControl from the URI passed to it and insert it into a host element. Because the resulting PageControl contains an error, the returned promise errors out. To trap the error raised during navigation, I add an error handler to the onError parameter of the then method exposed by that Promise object. This effectively traps the error, preventing it from raising the Application.onerror event.

Figure 6 The PageControlNavigator._navigating Function in navigator.js

// Other PageControlNavigator code ...
// Responds to navigation by adding new pages to the DOM.
_navigating: function (args) {
  var newElement = this._createPageElement();
  this._element.appendChild(newElement);
  this._lastNavigationPromise.cancel();
  var that = this;
  this._lastNavigationPromise = WinJS.Promise.as().then(function () {
    return WinJS.UI.Pages.render(args.detail.location, newElement,
       args.detail.state);
  }).then(function parentElement(control) {
    var oldElement = that.pageElement;
    // Cleanup and remove previous element
    if (oldElement.winControl) {
      if (oldElement.winControl.unload) {
        oldElement.winControl.unload();
      }
      oldElement.winControl.dispose();
    }
    oldElement.parentNode.removeChild(oldElement);
    oldElement.innerText = "";
  },
  // Display any errors raised by a page control,
  // clear the backstack, and cancel the error.
  function (err) {
    var messageDialog =
      new Windows.UI.Popups.MessageDialog(
        err.message,
        "Sorry, can't navigate to that page.");
    messageDialog.showAsync()
    nav.history.backStack.pop();
    return true;
  });
  args.detail.setPromise(this._lastNavigationPromise);
},
// Other PageControlNavigator code ...

Promises in WinJS

Creating promises and chaining promises—and the best practices for doing so—have been covered in many other places, so I’ll skip that discussion in this article. If you need more information, check out the blog post by Kraig Brockschmidt at bit.ly/1cgMAnu or Appendix A in his free e-book, “Programming Windows Store Apps with HTML, CSS, and JavaScript, Second Edition” (bit.ly/1dZwW1k).

Note that it’s entirely proper to modify navigator.js. Although it’s provided by the Visual Studio project template, it’s part of your app’s code and can be modified however you need.

In the _navigating function, I’ve added an error handler to the final promise.then call. The error handler shows a message dialog—as with the application-level error handling—and then cancels the error by returning true. It also removes the page from the navigation history.

When I run the sample again and navigate to handlingErrors.html, I see the message dialog that informs me the navigation attempt has failed. The message dialog from the application-level error handling doesn’t appear.

Tracking Down Errors in Asynchronous Chains

When building apps in JavaScript, I frequently need to follow one asynchronous task with another, which I address by creating promise chains. Chained promises will continue moving along through the tasks, even if one of the promises in the chain returns an error. A best practice is to always end a chain of promises with a call to the done method. The done function throws any errors that would’ve been caught in the error handler for any previous then statements. This means I don’t need to define error functions for each promise in a chain.

Even so, tracking errors down can be difficult in very long chains once they’re trapped in the call to promise.done. Chained promises can include multiple tasks, and any one of them could fail. I could set a breakpoint in every task to see where the error pops up, but that would be terribly time-consuming.

Here’s where Visual Studio 2013 comes to the rescue. The Tasks window (introduced in Visual Studio 2010) has been upgraded to handle asynchronous JavaScript debugging as well. In the Tasks window you can view all active and completed tasks at any given point in your app code.

For this next example, I’ll add a new page to the solution to demonstrate this awesome tool. In the solution, I create a new folder called chainedAsync in the pages folder and then add a new Page Control named chainAsync.html (which creates /pages/­chainedAsync/chainedAsync.html and associated .js and .css files).

In chainedAsync.html, I insert the following markup within the <section> tags:

<!-- ERROR:Clicking this button starts a chain reaction with an error. -->
<p><button id="startChain">Start the error chain</button></p>
<p id="output"></p>

In chainedAsync.js, I add the event handler shown in Figure 7for the click event of the startChain button to the ready method for the page.

Figure 7 The Contents of the PageControl.ready Function in chainedAsync.js

startChain.addEventListener("click", function () {
  goodPromise().
    then(function () {
        return goodPromise();
    }).
    then(function () {
        return badPromise();
    }).
    then(function () {
        return goodPromise();
    }).
    done(function () {
        // This *shouldn't* get called
    },
      function (err) {
          document.getElementById('output').innerText = err.toString();
    });
});

Last, I define the functions goodPromise and badPromise, shown in Figure 8, within chainAsync.js so they’re available inside the PageControl’s methods.

Figure 8 The Definitions of the goodPromise and badPromise Functions in chainAsync.js

function goodPromise() {
  return new WinJS.Promise(function (comp, err, prog) {
    try {
      comp();
    } catch (ex) {
      err(ex)
    }
  });
}
// ERROR: This returns an errored-out promise.
function badPromise() {
  return WinJS.Promise.wrapError("I broke my promise :(");
}

I run the sample again, navigate to the “Chained asynchronous” page, and then click “Start the error chain.” After a short wait, the message “I broke my promise :(” appears below the button.

Now I need to track down where that error occurred and figure out how to fix it. (Obviously, in a contrived situation like this, I know exactly where the error occurred. For learning purposes, I’ll forget that badPromise injected the error into my chained promises.)

To figure out where the chained promises go awry, I’m going to place a breakpoint on the error handler defined in the call to done in the click handler for the startChain button, as shown in Figure 9.

Figure 9 The Position of the Breakpoint in chainedAsync.html

I run the same test again, and when I return to Visual Studio, the program execution has stopped on the breakpoint. Next, I open the Tasks window (Debug | Windows | Tasks) to see what tasks are currently active. The results are shown in Figure 10.

Figure 10 The Tasks Window in Visual Studio 2013 Showing the Error

At first, nothing in this window really stands out as having caused the error. The window lists five tasks, all of which are marked as active. As I take a closer look, however, I see that one of the active tasks is the Scheduler queuing up promise errors—and that looks promising (please excuse the bad pun).

(If you’re wondering about the Scheduler, I encourage you to read the next article in this series, where I’ll discuss the new Scheduler API in WinJS.)

When I hover my mouse over that row (ID 120 in Figure 10) in the Tasks window, I get a targeted view of the call stack for that task. I see several error handlers and, lo and behold, badPromise is near the beginning of that call stack. When I double-click that row, Visual Studio takes me right to the line of code in badPromise that raised the error. In a real-world scenario, I’d now diagnose why badPromise was raising an error.

WinJS provides several levels of error handling in an app, above and beyond the reliable try-catch-finally block. A well-performing app should use an appropriate degree of error handling to provide a smooth experience for users. In this article, I demonstrated how to incorporate app-level, page-level and navigation-level error handling into an app. I also demonstrated how to use some of the new tools in Visual Studio 2013 to track down errors in chained promises.

How To : Use the Microsoft Monitoring Agent to Monitor apps in deployment

You can locally monitor IIS-hosted ASP.NET web apps and SharePoint 2010 or 2013 applications for errors, performance issues, or other problems by using Microsoft Monitoring Agent. You can save diagnostic events from the agent to an IntelliTrace log (.iTrace) file. You can then open the log in Visual Studio Ultimate 2013 to debug problems with all the Visual Studio diagnostic tools.

If you use System Center 2012, use Microsoft Monitoring Agent with Operations Manager to get alerts about problems and create Team Foundation Server work items with links to the saved IntelliTrace logs. You can then assign these work items to others for further debugging.

See Integrating Operations Manager with Development Processes and Monitoring with Microsoft Monitoring Agent.

Before you start, check that you have the matching source and symbols for the built and deployed code. This helps you go directly to the application code when you start debugging and browsing diagnostic events in the IntelliTrace log. Set up your builds so that Visual Studio can automatically find and open the matching source for your deployed code.

1. Set up Microsoft Monitoring Agent.
2. Start monitoring your app.
3. Save the recorded events.

Step 1: Set up Microsoft Monitoring Agent

Set up the standalone agent on your web server to perform local monitoring without changing your application. If you use System Center 2012, see Installing Microsoft Monitoring Agent.

Set up the standalone agent

1. Make sure that:
   • Your web server is running supported versions of Internet Information Services (IIS).
   • Your web server has .NET Framework 3.5, 4, or 4.5.
   • Your web server is running Windows PowerShell 3.0 or later. What if I have Windows PowerShell 2.0?
   • You have administrator permissions on your web server to run PowerShell commands and to recycle the application pool when you start monitoring.
   • You’ve uninstalled any earlier versions of Microsoft Monitoring Agent.
2. Download the free Microsoft Monitoring Agent, either the 32-bit version MMASetup-i386.exe or 64-bit version MMASetup-AMD64.exe, from the Microsoft Download Center to your web server.
3. Run the downloaded executable to start the installation wizard.
4. Create a secure directory on your web server to store the IntelliTrace logs, for example, C:\IntelliTraceLogs.

   Make sure that you create this directory before you start monitoring. To avoid slowing down your app, choose a location on a local high-speed disk that’s not very active.

    

   Security Note
   IntelliTrace logs might contain personal and sensitive data. Restrict this directory to only those identities that must work with the files. Check your company’s privacy policies.

5. To run detailed, function-level monitoring or to monitor SharePoint applications, give the application pool that hosts your web app or SharePoint application read and write permissions to the IntelliTrace log directory. How do I set up permissions for the application pool?

Q: What if I have Windows PowerShell 2.0?

Use the Windows PowerShell Start-WebApplicationMonitoring command to start monitoring your app. If you use System Center 2012, see Monitoring Web Applications with Microsoft Monitoring Agent.

Q: How do I set up permissions for the application pool?

Step 2: Start monitoring your app

1. On your web server, open a Windows PowerShell or Windows PowerShell ISE command prompt window as an administrator.

    

    

2. Run the Start-WebApplicationMonitoring command to start monitoring your app. This will restart all the web apps on your web server.

    

   Here’s the short syntax:

    

   Start-WebApplicationMonitoring “<appName>” <monitoringMode> “<outputPath>” <UInt32> “<collectionPlanPathAndFileName>”

    

   Here’s an example that uses just the web app name and lightweight Monitor mode:

    

   PS C:\>Start-WebApplicationMonitoring “Fabrikam\FabrikamFiber.Web” Monitor “C:\IntelliTraceLogs”

    

   Here’s an example that uses the IIS path and lightweight Monitor mode:

    

   PS C:\>Start-WebApplicationMonitoring “IIS:\sites\Fabrikam\FabrikamFiber.Web” Monitor “C:\IntelliTraceLogs”

    

   After you start monitoring, you might see the Microsoft Monitoring Agent pause while your apps restart.

    

    

   “<appName>”	Specify the path to the web site and web app name in IIS. You can also include the IIS path, if you prefer.   “<IISWebsiteName>\<IISWebAppName>” -or- “IIS:\sites \<IISWebsiteName>\<IISWebAppName>”   You can find this path in IIS Manager. For example:     You can also use the Get-WebSite and Get WebApplication commands.
   <monitoringMode>	Specify the monitoring mode:   Monitor: Record minimal details about exception events and performance events. This mode uses the default collection plan. Trace: Record function-level details or monitor SharePoint 2010 and SharePoint 2013 applications by using the specified collection plan. This mode might make your app run more slowly.   Make sure that the application pool has read and write permissions to the IntelliTrace log directory. How can I get the most data without slowing down my app?   This example records events for a SharePoint app hosted on a SharePoint site:   Start-WebApplicationMonitoring “FabrikamSharePointSite\FabrikamSharePointApp” Trace “C:\Program Files\Microsoft Monitoring Agent\Agent\IntelliTraceCollector\collection_plan.ASP.NET.default.xml” “C:\IntelliTraceLogs”   Custom: Record custom details by using specified custom collection plan. You’ll have to restart monitoring if you edit the collection plan after monitoring has already started.
   “<outputPath>”	Specify the full directory path to store the IntelliTrace logs. Make sure that you create this directory before you start monitoring.
   <UInt32>	Specify the maximum size for the IntelliTrace log. The default maximum size of the IntelliTrace log is 250 MB. When the log reaches this limit, the agent overwrites the earliest entries to make space for more entries. To change this limit, use the -MaximumFileSizeInMegabytes option or edit the MaximumLogFileSize attribute in the collection plan.
   “<collectionPlanPathAndFileName>”	Specify the full path or relative path and the file name of the collection plan. This plan is an .xml file that configures settings for the agent. These plans are included with the agent and work with web apps and SharePoint applications: collection_plan.ASP.NET.default.xml Collects only events, such as exceptions, performance events, database calls, and Web server requests. collection_plan.ASP.NET.trace.xml Collects function-level calls plus all the data in default collection plan. This plan is good for detailed analysis but might slow down your app.   You can find localized versions of these plans in the agent’s subfolders. You can also customize these plans or create your own plans to avoid slowing down your app. Put any custom plans in the same secure location as the agent.   How else can I get the most data without slowing down my app?

    

   For the more information about the full syntax and other examples, run the get-help Start-WebApplicationMonitoring –detailed command or the get-help Start-WebApplicationMonitoring –examples command.

3. To check the status of all monitored web apps, run the Get-WebApplicationMonitoringStatus command.

Microsoft Application Insights – A comprehensive guide : Part 1 – Getting Started

Application Insights Overview

With Application Insights, we have the same excellent capabilities from the Application Performance Monitoring (APM) feature (formerly AviCode) available in SCOM 2012 R2 – with the exception that it’s all run from the cloud as part of Visual Studio Online. With this type of monitoring for your applications, you can ensure that they are available and performing optimally, while leveraging usage data to drive improvements and trends.

In relation to the Microsoft Management Agent used for both Application Insights and SCOM 2012 R2, they share the same source code but have a slight difference with serialization that determines which REST interface and location the agent sends its performance data to.

Application Insights supports both .NET and Java web applications. On the Java side of the house, it supports monitoring Tomcat 6, Tomcat 7 or JBoss 6. For the purposes of this deep-dive series however, I’m going to concentrate on demonstrating its capabilities monitoring .NET web applications and I’ll save the Java monitoring for a later post.

You can use Application Insights to monitor web applications that are running in an on-premise/virtual machine scenario and of course, it’s also fully supported to monitor web applications running as a web role in Windows Azure Cloud Services. If you’re a Windows Phone app developer, you might be interested in the capability to view usage trends and other analytical data as users download and use your app on a daily basis.

The method of getting these different environments monitored varies depending on scenario but typically, it’s a straight-forward enough process as you’ll understand when you read through this blog series.

Regardless of the environment you’re monitoring with Application Insights, you can ensure you’re kept up to date with any performance issues (slow responses, uncaught exceptions etc.) by enabling email notification direct to your inbox. If you want to use Visual Studio to view the stack trace to help triage the problem, then this is an easy option too.

So, that’s a high-level overview of what Application Insights can do, now let’s get started!

Creating Your Account

The first thing you’ll need to do is to create a new Visual Studio Online account by clicking on the following link to sign up:

http://www.visualstudio.com/products/visual-studio-online-overview-vs

Click on the ‘Ready to Go?’ tile

Enter your Microsoft Account (formerly Windows Live ID) details, then click the Sign In button. If you don’t yet have a Microsoft Account, you can sign up for a new one here.

Input all your details into the ‘Create a Visual Studio Online Account’ window, then hit the Create Account button to move on.

Once you’ve created your Visual Studio Online account, you’ll need to specify a name for your first project. Call it what you want, then hit the Create Project button to finish.

Now, at the Overview screen of your Home page, you should see a Blue tile titled ‘Try Application Insights’ as shown below. If you can’t see the Blue AI tile, then click the Help button and choose the ‘Display Announcement’ option from the resulting menu.

Click on the Blue tile and you’ll be taken to the *Insights view where you’ll be prompted for an invitation code to gain access

Invitation Code? I hear you ask.

Don’t worry if you don’t have one, even though AI is still only available as a Preview, the good folks over at Microsoft have made a public code available at the following link:

http://blogs.msdn.com/b/visualstudioalm/archive/2014/01/13/invitation-code-for-trialing-application-insights.aspx

Type in your code, then hit the Get Started button to enter the new world of Application Insights!

That’s it for Part 1 of this series. In Part 2, we’ll start work on building a demo .NET web application environment for us to give our new Application Insights account a test drive in.

Troubleshooting issues with the “Eligible MSDN Subscriber” license type

As you adopt Visual Studio Online (VSO) and assign licenses to your users you may want to assign the “Eligible MSDN Subscriber” license type to team members. MSDN subscriptions are purchased outside of VSO and assigned to individual users. Before an MSDN subscriber can log in to VSO as an eligible MSDN subscriber, the subscription process must first be completed. The general flow looks like this:

• MSDN subscription is purchase by or assigned to a team member. Assignment could be via the Volume Licensing Service Center, MPN, etc.
• Team member receives an email asking them to activate their subscription by signing in with a Microsoft account and registering with the subscription details provided.
• Team member activates the subscription and associates a Microsoft account (MSA) with the subscription. The team member logs in to msdn.microsoft.com/en-us/subscriptions/manage using this MSA to manage the subscription going forward.
• A VSO admin adds the MSA (the one the team member associated with their subscription in the previous step) to the Users Hub (https://Contoso.visualstudio.com/_user) and assigns them an “Eligible MSDN Subscriber” license.
• If 24-48 hours have passed since the subscription was activated, the team member should be able to log in to VSO as an “Eligible MSDN Subscriber” and enjoy full access to all VSO features (a benefit of this license level).

 

Sometimes though the team member may run into problems after this process. Specifically, they may try to log in and receive an error: 

 

Figure 1: (403 Forbidden \ …does not have license rights to access this account \ VSS012019: No MSDN subscription found for this user)

 

The team member could be seeing this error for a number of reasons: 

1. The specific MSDN subscription may not be eligible for Visual Studio Online access
Not all MSDN subscription types include VSO as a benefit. Please refer to the list of eligible MSDN subscriptions to verify.

 

2. The MSDN subscription was assigned to the user within the last 48 hours
There is a delay between MSDN subscription assignments and when VSO will see it \ allow the user to log in. If the subscription was assigned less than 24 hours ago please wait 24-48 hours and have the user try again.

 

3. The “Software Downloads” benefit has not been provided with the MSDN subscription
VSO usage is tied to the “Software Downloads” benefit of an MSDN subscription. In order to access VSO when assigned the “Eligible MSDN Subscriber” license type, the user’s MSDN subscription must include this “Software Downloads” benefit.  Here’s an example of enabling that benefit via the Volume Licensing Service Center:

 

 

4. The wrong email address has been added to the VSO Users Hub
This one is important. When an MSDN subscription is assigned to a user they receive an email (usually to their work email address) asking them to associate their new MSDN subscription with a Microsoft account\email address (MSA). This could be the same address where they received the mail or the user could pick a completely different MSA. The MSA they pick to associate with their new MSDN subscription is the one that needs to be added to the VSO Users Hub (https://Contoso.visualstudio.com/_user) and assigned the “Eligible MSDN Subscriber” license. It’s the one they use to manage their MSDN subscription via https://msdn.microsoft.com/subscriptions/manage.

Check with your user to see what MSA they’ve associated with & use to manage their MSDN subscription, and ensure that’s the one on the Users Hub.

 

If all this checks out, have the team member try this:

1. Go to msdn.microsoft.com/en-us/subscriptions/manage and log in with your Microsoft account
2. From the “My Subscriptions” section in the top-left, copy the name, email and Subscriber ID for the MSDN subscription you want to use with VSO. Paste this into Notepad or other text editor.
3. Click “Add an existing subscription to my account” in the “My Subscriptions” section in the top-left.
4. Fill out the form with the values you copied in step # 3 and then click NEXT.
5. Acknowledge and accept the license notice and then click ACCEPT.

This will not change your subscription in any way but will essentially reactivate it and with any luck this will allow you to log in to VSO.

 

I hope you are not having any issues with the “Eligible MSDN Subscriber” license type in VSO, but if you are please run through this checklist to try and fix them. If you are still blocked, please open support case and we can assist:

• Go to http://www.visualstudio.com/support-overview-vs
• Click Visual Studio Online tile in the “3. Answer wasn’t there? Talk to us” section