Hands-On LabIntroduction to PreEmptive AnalyticsLab version: 14.0.23107.0

Last updated: 9/11/2015

TABLE OF CONTENT

INTRODUCTION TO PREEMPTIVE ANALYTICS...........................................................................1

OVERVIEW.....................................................................................................................................3

Prerequisites...........................................................................................................................4

Exercises.................................................................................................................................4

EXERCISE 1: INSTALLING PREEMPTIVE ANALYTICS COMMUNITY EDITION...................................................5

Task 1: Install PreEmptive Analytics Components...............................................................5

Task 2: Connect to Team Project Collection......................................................................14

EXERCISE 2: INSTRUMENTING AN APPLICATION...................................................................................18

Task 1: Setup Scenario to Produce Application Error........................................................18

Task 2: Instrument Application using Dotfuscator............................................................20

EXERCISE 3: MAPPING THE APPLICATION TO CREATE INCIDENTS IN TFS..................................................30

EXERCISE 4: VIEWING INCIDENTS IN TFS...........................................................................................35

Overview

PreEmptive Analytics Community Edition for Team Foundation Server is a third party tool created by PreEmptive which allows you to gain insight into errors experienced by your customers. By instrumenting your application for analytics, you’ll be able to see these exceptions in Visual Studio Team Foundation Server 2015 so you can easily triage them right alongside your bugs. Exceptions are analyzed, correlated, and distilled into a set of “production incidents” based on the rules and operational thresholds you specify.

Figure 1High-level overview of PreEmptive Analytics working with instrumented application

Prerequisites

In order to complete this lab you will need the Visual Studio 2015 virtual machine provided by Microsoft. For more information on acquiring and using this virtual machine, please see this blog post.

Exercises

This hands-on lab includes the following exercises:

1. Installing PreEmptive Analytics Community Edition

2. Instrumenting an Application

3. Mapping the Application to Create Incidents in Visual Studio Team Foundation Server

4. Viewing Incidents in Visual Studio Team Foundation Server

Estimated time to complete this lab: 60 minutes.

Exercise 1: Installing PreEmptive Analytics Community Edition

In this exercise, you will learn how to install PreEmptive Analytics Community Edition in a locally hosted scenario.

Task 1: Install PreEmptive Analytics Components

1. Log in as Julia (VSALM\Julia). All user passwords are P2ssw0rd.

2. Launch the Team Foundation Server Administration Console from the taskbar.

3. Select the PreEmptive Analytics node under Additional Tools and Components. There is a link to install the PreEmptive Analytics Community Edition here, but instead let us say that we would like to install the components with some additional control over the configuration.

Figure 2PreEmptive Analytics setup page

4. Close the Team Foundation Server Administration Console window.

5. Execute the PreEmptive Analytics installer (PreEmptive.Analytics.Setup.exe) from c:\Program Files\Microsoft Team Foundation Server 14.0\Tools.

Figure 3Installing PreEmptive Analytics for TFS CE

6. Select the Next to continue the setup wizard.

Figure 4Location of Next button

7. Read the license terms, select the check box for I accept the terms of this agreement, and then select the Next button.

Figure 5 License terms page

8. Select the Advanced installation type.

Figure 6Advanced installation type

9. Select the option to install a Combined Endpoint & Aggregator.

Figure 7Installing PreEmptive server components

10. On the Aggregator Service Configuration page, enter VSALM\Julia as the TFS Account Name, P2ssw0rd as the password, and then select Next.

Figure 8Enter the TFS account information

Note: The aggregator service must be hosted on a TFS server and have the permissions necessary to create and edit work items.

11. On the Exception Endpoint IIS Configuration page, change the port to 1500 (the default port is already in use in IIS) and then select the Next button.

Figure 9Configuring exception endpoint

12. On the Exception Endpoint SQL Configuration page, select the Next button to accept the defaults.

Figure 10SQL configuration

13. Select Install to begin the installation for PreEmptive Analytics for TFS CE. This will take a few minutes to complete.

Figure 11Location of the Install button

Note: When performing a complete installation like this, all components will be installed to the same machine. The PreEmptive Analytics Aggregator service will be installed and set to start automatically. A new database will be created in your local instance of SQL Server to store exception report data and a new website will be created in IIS to host the PreEmptive Analytics endpoint message & query services (which receive exception report messages from instrumented applications and provide access to stored messages).

14. Once the installation is finished, take a note of the endpoint shown in the dialog. This endpoint will be used later in the lab as the custom endpoint. Select Close to leave the setup program.

Figure 12Location of the Close button

Task 2: Connect to Team Project Collection

1. The PreEmptive Analytics Aggregator Administration Console will be automatically launched after setup has completed.

Figure 13PreEmptive Analytics Aggregator Administration Console

2. Select the “+” button to add a connection to a Team Project Collection.

Figure 14Location of the “+” sign

3. In the Connect to Team Project Collection dialog, select FabrikamFiberCollection in Team Project Connections and select the Connect button.

Figure 15Connect to Team Project Collection

4. Select the Apply button next to the FabrikamFiber project. This will take a few minutes to complete.

Figure 16Location of the Apply button

Note: Provisioning TFS projects to work with PreEmptive Analytics involves importing the Incident work item type and some sample PreEmptive Analytics reports into the project template. In addition, the project is configured with settings that the PreEmptive Analytics Visual Studio extension needs in order to be able to configure exception sets and rules.

5. PreEmptive Analytics is now setup with the FabrikamFiber project and is ready to accept exceptions from instrumented applications. We will setup a subscription in a later exercise.

Figure 17PreEmptive Analytics registered with team project

Exercise 2: Instrumenting an Application

In this exercise, you will learn how to instrument an existing application using PreEmptive Dotfuscator and Analytics.

Task 1: Setup Scenario to Produce Application Error

1. Launch Visual Studio 2015 from the taskbar and open Team Explorer. You should now be connected to the FabrikamFiber team project. If you are not automatically connected to the

FabrikamFiber project, select the Connect to Team Projects button ( ) to do so.

2. In Team Explorer – Home, double-click on the first FabrikamFiber.CallCenter.sln solution.

Figure 18Loading FabrikamFiber.CallCenter solution

3. Now we will modify the source code and add an exception for the purpose of this lab. Go to Solution Explorer and open ServiceTicketsController.cs under FabrikamFiber.Web | Controllers.

4. Scroll down to the Create method and add the following line.

C#

throw new Exception("Testing global error handler!");

Figure 19Add an exception in Create method

5. Select Build | Rebuild Solution from the main menu to initiate a clean rebuild.

Task 2: Instrument Application using Dotfuscator

1. Now we need to instrument the web application so that exception information makes its way back to us. To do this, we will use the PreEmptive Dotfuscator and Analytics tool to configure the exception endpoint address and to identify the application source.

2. Open Dotfuscator and Analytics Community Edition by selecting Tools | PreEmptive Dotfuscator and Analytics.

3. The PreEmptive Dotfuscator and Analytics CE tool is launched.

Figure 20PreEmptive Dotfuscator and Analytics CE

4. Select the Inputs node followed by the Add Input button.

Figure 21

Add Input

5. Navigate to C:\Users\Julia\Source\Workspaces\FabrikamFiber\Dev\FabrikamFiber.CallCenter\FabrikamFiber.Web\bin, select FabrikamFiber.Web.dll, and finally select Open. Please ensure that you are logged in as Julia.

Figure 22Select input

6. Select the Analytics node under Configuration Options, and then select the Attributes tab.

Figure 23Location of Analytics and Attributes buttons

7. Right-click on the root node and select Add Attribute.

Figure 24Location of Add Attribute option

8. In the Add Attribute dialog, select PreEmptive.Attributes.ApplicationAttribute, then select OK. This attribute defines a GUID that ensures that data from this application stays separate from other applications that our company releases.

Figure 25Add the Application attribute

9. This is the place to enter the name, version and a unique identifier for the application. For the purpose of this lab, we will just use a randomly generated GUID by clicking on the space next to Guid and then selecting the … button.

Figure 26Generating an application GUID

Figure 27Application GUID generated

Note: The GUID that you see will be different from what is shown in lab screenshots.

10. Right-click on the root node and select Add Attribute to add the PreEmptive.Attributes.BusinessAttribute and select OK. This attribute distinguishes our company using a GUID provided by PreEmptive.

Figure 28Add the BusinessAttribute

11. Notice that the CompanyKey field has already been filled in.

Figure 29The Business Attribute

12. Next we need to specify the methods that denote where we want to begin and end data gathering by using SetupAttribute and TeardownAttribute.

13. Expand FabrikamFiber.Web.dll | FabrikamFiber.Web.App_Start | NinjectMVC3, right-click on Start : void() and select Add Attribute.

Figure 30Add Attribute to Start:void ()

14. Select PreEmptive.Attributes.SetupAttribute, and select OK. This attribute will designate where we would like to begin data gathering as well as the exception endpoint to use.

Figure 31Add the Setup attribute

15. Click on the space next to the StaticEndpoint property and enter the endpoint we were given during the setup of PreEmptive Analytics, VSALM:1500/message/Endpoint.ashx.

Figure 32Configuring endpoint

Note: If you clicked on the ellipses (…) button for the CustomEndpoint property, you would also see options for using PreEmptive’s hosted endpoints.

16. Right-click on Stop:void()and select Add Attribute. This attribute simply designates the point where we want to stop collecting data.

Figure 33Add attribute to Stop:void()

17. Select PreEmptive.Attributes.TeardownAttribute, and select the OK button.

Figure 34Add the Teardown attribute

18. At this point, our application is configured to send data to the configured endpoint. Now let’s see how we can specify that some exception data should be collected.

19. Expand FabrikamFiber.Web.dll | FabrikamFiber.Web.Controllers | ServiceTicketsController, right-click on Create : System.Web.Mvc.ActionResult() and select Add Attribute.

Figure 35Add Attribute to Create method

20. Select the PreEmptive.Attributes.ExceptionTrackAttribute, and select the OK button. Since we are applying this to a specific method, only locally unhandled exceptions will be tracked.

Figure 36 Add the ExceptionTrack attribute

21. Select the Renaming node under Configuration Options, and then select the Options tab.

Figure 37Setting renaming options

22. Uncheck the Enable Renaming option.

Figure 38Location of the ‘Enable renaming’ check box

23. Save the configuration changes by selecting the Save button.

Figure 39Location of the Save button

24. Enter FabrikamFiber.Dotfuscator as the name of the project file, then select Save.

Figure 40Enter file name and save

25. Select the Build Project button in the PreEmptive Dotfuscator and Analytics CE window. This will modify the FabrikamFiber.Web.dll assembly with the specified instrumentation included. In the next exercise, we will create a subscription for the application so the generated exceptions will appear in TFS.

Figure 41The location of the Build Project button

Exercise 3: Mapping the Application to Create Incidents in TFS

In this exercise, you will learn how to map the data collected from the instrumented application to Team Foundation Server.

1. Return to Visual Studio and navigate to Team Explorer - Home to locate the PreEmptive Analytics hub. Team Explorer only shows the PreEmptive Analytics hub for team projects that have PreEmptive Analytics applied to them.

2. Select the PreEmptive Analytics tile to load the PreEmptive Analytics view.

Figure 42Team Explorer hub showing PreEmptive Analytics hub

3. Select the Configure link. This will load the PreEmptive Analytics Options window.

Figure 43Location of the Configure button

4. Add a subscription by selecting the ‘+’ button.

Figure 44Location of the ‘+’ button

5. Use Fabrikam Fiber for the name.

Figure 45Enter the name

6. Go back to the PreEmptive Dotfuscator and Analytics CE window. Copy the generated CompanyKey from the PreEmptive.Attributes.BusinessAttribute attribute (7d2b02e0-064d-49a0-bc1b-4be4381c62d3) and paste it in as the Company ID in the PreEmptive Analytics Options window.

Figure 46Location of the CompanyKey in PreEmptive Dotfuscator and Analytics CE

Figure 47Location of the Company ID in PreEmptive Analytics Options

7. Go back to the PreEmptive Dotfuscator and Analytics CE window. Copy the generated Application Guid from the PreEmptive.Attribute.ApplicationAttribute attribute and paste it in as the Application ID in the PreEmptive Analytics Options window.

Figure 48Location of the Application GUID In PreEmptive Dotfuscator and Analytics CE

Figure 49Location of the Application ID in PreEmptive Analytics Options

Note: You will see a different GUID for Application ID from the figures shown in the lab manual.

8. For the purpose of this lab, set the rule Threshold to 1 so we can see the incident report after just one exception. Select the Close button.

Figure 50Location of the Threshold and Close button

9. Select Yes when asked to confirm saving.

Figure 51Location of the Yes button

10. The last step is to deploy the FabrikamFiber.Web.dll built by Dotfuscator to production. Use Windows Explorer and navigate to C:\Users\Julia\Source\Workspaces\FabrikamFiber\Dev\FabrikamFiber.CallCenter\FabrikamFiber.Web\bin\Dotfuscated. Copy the FabrikamFiber.Web.dll from the Dotfuscated directory and paste it to C:\inetpub\FabrikamFiber.Web\bin, the directory for the product site. When prompted, it is OK to replace the existing copy of the file.

Figure 52 Deploying the instrumented assembly to production

Note: We recommend that you to reset the virtual machine after this lab is complete, given the change to the production web site for Fabrikam Fiber.

11. Next, we will cause an exception to occur and then view the resulting incident work item in TFS.

Exercise 4: Viewing Incidents in TFS

In this exercise, you will see PreEmptive Analytics in action as the instrumented application hits the exception, pushes data to the configured endpoint, and an incident is surfaced to Team Foundation Server.

1. Launch Internet Explorer and select FF Intranet from the favorites bar to load the Fabrikam Fiber intranet site.

Figure 53Fabrikam Fiber Intranet site

2. Select the Create New button. This will throw the exception.

Figure 54Location of the Create New button

Figure 55Exception caused by selecting the “Create New” button.

3. Go back to Visual Studio. In Team Explorer – PreEmptive Analytics, select the All Incidents query.

Figure 56Loading query to view all incidents

4. If no results are found at first, you may need to wait a few minutes and then Refresh so that the aggregator has a chance to do its job. Once the incident work item appears, you should be able to see the stack trace at the time that the exception occurred, as well as how many times the exception was experienced by customers (see Raw Exception Count).

Figure 57Incident view

Note: In the event that you experience trouble with PreEmptive Analytics, check the event log for more information. In addition, see the Troubleshooting section of the help file located in the PreEmptive Solutions installation folder (C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics for TFS CE\doc on the VM).

To give feedback please write to VSKitFdbk@Microsoft.com

Copyright © 2023 by Microsoft Corporation. All rights reserved.