Hands-On LabUsing Access Services with SharePoint OnlineLab version: 1.0

Last updated: 5/24/2023

CONTENTS

OVERVIEW................................................................................................................................................. 3System Requirements..............................................................................................................................3

SETUP........................................................................................................................................................ 3Task 1 – Create SharePoint Online Site................................................................................................3

Task 2 – Prepare Code Snippets...........................................................................................................4

EXERCISE 1 – PUBLISH AN ACCESS DATABASE TO SHAREPOINT ONLINE....................................4Task 1 – Publish an Access Help Desk Database to your SharePoint Online........................................4

Task 2 – Explore the Access Services Web...........................................................................................6

EXERCISE 2 – LOGGING EXCEPTIONS...................................................................................................9Task 1 – Create Visual Web Part to throw a SharePoint exception....................................................10

Task 2 – Create a class library to handle SharePoint exceptions.......................................................11

Task 3 – Log exceptions from the SharePoint Visual Web with the Utilities project..........................13

Task 4 – Test the solution on-premises.............................................................................................14

Task 5 – Test the solution in SharePoint Online.................................................................................16

SUMMARY................................................................................................................................................ 21

Overview

Lab Time: 20 minutes.

Lab Folder: C:\%Office365TrainingKit%\Labs\5.2\Source\Before

Lab Overview: In this lab, you will learn how to use SharePoint Access Services to publish an existing Microsoft Access database to SharePoint Online. Doing so will create a new SharePoint web and convert Access tables into SharePoint lists, and Access forms into corresponding HTML and CSS. By publishing a database to SharePoint Online, you allow everyone with access to your site to interact with an Access database without the complexities of sharing an access database file (.accdb).

In the first exercise, you will explore the newly created site to view the site lists that correspond to the Access tables. Next, you will update one of the lists and see the corresponding SharePoint website and Access database updated.

The second exercise will leverage this database to demonstrate how to prepare for and handle exceptions in your solutions after the solution has been deployed to SharePoint Online. You will do this by proactively catching any exceptions and logging the details to a list that was defined as part of publishing the database to SharePoint online.

System Requirements

You must have the following items to complete this lab:

SharePoint 2010

Visual Studio 2010

SharePoint Designer 2010

SharePoint Online site

◦ Note: You will need administrator access to an SPO site collection to perform the steps in this lab.

Setup

Note: These setup instructions apply to all the labs in this unit; you don’t need to repeat these steps if you already performed them in the first lab in the unit.

Task 1 – Create SharePoint Online Site

In this task, you will create a sub site for this lab in your SharePoint Online site.

1. Navigate to your top-level SharePoint Online site, e.g., https://contoso.sharepoint.com.

2. From Site Actions, choose New Site.

3. Choose the Express Site template.

4. Enter Lab05 for the name of the site to create.

a. The site will be created at <Your SharePoint Online URL>/Lab05, e.g., https://contoso.sharepoint.com/Lab05.

5. Click Create to create the site.

Note: You have to be an administrator on your SharePoint Online website to perform the tasks in this lab, e.g., creating and publishing a SharePoint Designer workflow to the SharePoint Online site.

Task 2 – Prepare Code Snippets

This lab contains code snippets that you will use to complete the solution. You can either copy the snippets from the lab script itself or install the code snippets so that you can access them directly from Visual Studio.

1. Browse to C:\%Office365TrainingKit%\Assets\Code Snippets

2. Select all the files in this directory and copy them to your clipboard by pressing [Ctrl]+[a] and then [Ctrl]+[c].

3. Browse to ..\Documents\Visual Studio 2010\Code Snippets\Visual C#\My Code Snippets Press [Ctrl]+[v] to paste the code snippet files into this directory.

Note: To reduce typing, you can right-click where you want to insert source code, select Insert Snippet, select My Code Snippets and then select the entry matching the current exercise step.

Exercise 1 – Publish an Access database to SharePoint Online

Task 1 – Publish an Access Help Desk Database to your SharePoint Online

In this task, you will publish an existing Access Help Desk database to SharePoint Online. During publishing, access tables are converted to lists, and access forms are converted to the corresponding HTML/CSS.

1. Open the existing access database from C:\%Office365TrainingKit%\Labs\5.2\Source\Before\Help Desk.accdb.

2. Take some time to view the existing database. Browse the existing open issues and closed issues.

3. Select File >> Save & Publish >> Publish To Access Services.

4. Server URL: your SharePoint Online Lab05 sub site, e.g., https://contoso.sharepoint.com/Lab05

5. Site Name: Help Desk.

6. Select Run Compatibility checker.

Note: This confirms that the Access database is suitable for publishing to SharePoint. If it is not, access will create a report of all incompatible objects.

7. Select Publish to Access Services. This may take a few minutes.

8. Open your newly created Help Desk site by navigating to the URL <Your SharePoint Online URL>/Lab05/Help Desk, e.g., https://contoso.sharepoint.com/Lab05/Help Desk.

Task 2 – Explore the Access Services Web

In this task, you will explore details of the Access Services web that is created when you publish a database to SharePoint using Access Services. As stated earlier, during publishing, existing Access tables are converted to SharePoint lists and Access forms are converted to corresponding HTML and CSS. You will explore these lists and find where the corresponding HTML and CSS are stored. Next, you will insert an item into a list and see the corresponding Help Desk web and Access database update accordingly.

1. Open the Site Settings page by navigating to <SharePoint Online URL>/Lab05/Help Desk/_layouts/settings.aspx, e.g., https://contoso.sharepoint.com/Lab05/Help Desk/_layouts/settings.aspx.

Note: You need to navigate directly to the page since there is not a standard SharePoint menu created by Access services to access site settings

2. Select All Site Content.

3. You will see a standard SharePoint view of the site content within the application

Note the following lists and document libraries:

◦ AppImages – Do not modify this document library. It is an internal document library used by Access Services to store any images used within forms.

◦ Report Definitions – Do not modify this document library. It is an internal document library used by access services to store converted Access reports.

◦ Comments, Issues, Related Issues, Users – These are lists that correspond to the tables stored within Access. You can modify these tables through the client object model to programmatically add items to the Access database.

◦ MSysASO – Do not modify this list. It is an internal list used by Access services to render HTML in SharePoint online.

◦ Tasks 1 - Do not modify this list. It is an internal list used by Access services to track any workflows.

◦ USysApplicationLog - Do not modify this list. It is an internal list used by Access services to log application events.

4. Next, you will manually add an item to the Issues list and see the new item reflected in both SharePoint Online and Microsoft Access.

5. Begin by opening the Issues list.

6. Select Items >> New Item.

7. In the Summary textbox, enter the text “Send SharePoint Online credentials to accounting”.

8. Select the folder icon and navigate to the Help Desk web site by clicking on the link.

9. Note that the newly created issue is reflected in the SharePoint site.

10. Next, you will confirm that the newly created Issue is also reflected in Microsoft Access. Begin by opening Access and double clicking the Main form.

11. Note that the newly created issue is also reflected in Microsoft Access.

Exercise 2 – Logging Exceptions

Task 1 – Create Visual Web Part to throw a SharePoint exception

In this task, you will create a visual web part that will throw and catch an exception. Since developers using SharePoint Online will not have access to the ULS logs of any unhandled exceptions, developers must be proactive with their exception handling. In the case of this lab, you will be catching the exception. In later tasks, you will be logging the details of the exception to a SharePoint list using a custom, common exception handling assembly.

1. Launch Visual Studio 2010 and create a new empty SharePoint project by selecting File >> New >> Project.

2. In the New Project Dialog, select SharePoint >> 2010 in the Installed Templates section and choose Empty SharePoint Project.

3. Name the project Debugging. Save the project in C:\%Office365TrainingKit%\Labs\5.2\Source\Before

4. In the SharePoint Customization Wizard, enter the URL of the site you created for this session, e.g., http://intranet.contoso.com/Lab08 .

5. Select the Deploy as a sandboxed solution and click Finish.

6. Right-click the Debugging project in the Solution Explorer window and select Add >> New Item.

7. Choose Visual Web Part (Sandboxed).

8. Name the web part ExceptionGenerator.

9. Add a button to the form and create an event handler:

a. Switch ExceptionHandler.ascx to the Design View.

b. Select Toolbox.

c. Double click the Button icon to add a button to the form.

d. Change the text of the button from Button to Generate Exception.

e. Double click the newly-added button to open the click event handler (Button1_Click).

10. Enter the following code within the Button1_Click method. The actual exception handling will be performed later in Task 4.

Code Snippet (5.2.1)

C#

try{ throw new SPException("Sample exception " + DateTime.Now.ToString());}

catch (Exception ex){ //TODO: handle exception}

Task 2 – Create a class library to handle SharePoint exceptions

In this task, you will create a class library to handle all SharePoint exceptions. Developers can simply include this class in their SharePoint solutions and pass all caught exceptions to this class for appropriate handling.

1. Select File >> Add >> New Project…

2. In the Add New Project dialog, select Windows >> Class Library.

3. Name the project Utilities.

4. Right click on Class1.cs select Rename.

5. Name the file ExceptionHander.cs.

6. Add a reference to Microsoft.SharePoint.

a. Right click on the Utilities project.

b. In the Add Reference dialog, select the Browse Tab.

c. In the File Name dialog, enter C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI\Microsoft.SharePoint.dll

7. Add the following using statement under the existing using statements.

(Code Snippet 5.2.2)

C#

using Microsoft.SharePoint;using System.Security;

8. Add the following attribute above the namespace declaration.

(Code Snippet 5.2.3)

C#

[assembly: AllowPartiallyTrustedCallers]

Note: This attribute is required since all SharePoint sandboxed solutions are run in a partially-trusted context. Not including this attribute will result in a security exception.

9. Add the following code that will handle SharePoint exceptions within the ExceptionHandler Class. Since Access tables are converted to lists when they are published to SharePoint, you will insert a row into the “Issues” list which contains summary data about an issue. Next, you will insert an associated row into the “Comments” list. You will build up the exception

text in a separate method which will contain the exception details, including the exception message and stack trace.

(Code Snippet 5.2.4)

C#

public static void HandleSharePointException(Exception ex){ using (SPWeb helpDeskWeb = SPContext.Current.Web.Webs["Help Desk"]) { //Insert the exception message into the Issues list and mark it for Triage. SPList issuesList = helpDeskWeb.Lists["Issues"]; SPListItem newIssue = issuesList.Items.Add(); newIssue["Summary"] = ex.Message; newIssue["AssignedToUserID"] = 1; //Administrator newIssue["OpenedByUserID"] = 1; //Administrator newIssue.Update();

//Get the new identity ID for use when inserting the details of the exception into the comments list int newIssueID = (int)newIssue["ID"];

//Add the details of the exception to the comments list and associate it with our newly created issue. SPList commentsList = helpDeskWeb.Lists["Comments"]; SPListItem newComment = commentsList.Items.Add(); newComment["IssueID"] = newIssueID; newComment["Comment"] = BuildExceptionDetails(ex); newComment["CommentDate"] = DateTime.Now; newComment.Update(); }}

private static string BuildExceptionDetails(Exception ex){ //Create a formatted string containing a formatted exception StringBuilder retString = new StringBuilder(); retString.Append("Message: "); retString.Append(ex.Message); retString.Append("\r\n"); retString.Append("StackTrace: "); retString.Append(ex.StackTrace); retString.Append("\r\n"); retString.Append("Source: "); retString.Append(ex.Source); retString.Append("\r\n"); return retString.ToString();}

10. Right click on the Utilities project. Select Properties.

11. In the Target framework dropdown, select .NET Framework 3.5.

12. Click OK. Accept the warning from Visual Studio.

Note: You must change the framework version since SharePoint projects are compiled in the .NET Framework 3.5. SharePoint solutions cannot call assemblies compiled in the .NET Framework 4.0

13. Sign the assembly with a strong key.

Note: In order for an assembly to be included with a SharePoint solution package, it must have a strong name. Therefore, the assembly must be signed.

a. Select properties.

b. Select the Signing tab on the left.

c. Check the checkbox Sign the assembly.

d. In the Choose a strong name key file: dropdown, select <New…>.

e. Name the file key.snk.

f. Uncheck the checkbox Protect my key with a password.

14. Build the solution and confirm there are no compile-time errors.

Task 3 – Log exceptions from the SharePoint Visual Web with the Utilities project

In this task, you will handle exceptions thrown from the visual web part by sending them to the common utilities class that handles exceptions. In order to do this, you will need to add a reference to the Utilities class and deploy the class in your SharePoint package.

1. In the Debugging project, right click on references and select Add Reference…

2. Select the Utilities Project and click OK.

3. Open ExceptionGenerator.ascx.cs.

4. Replace the code:

C#

//TODO: handle Exception

With the code:

(Code Snippet 5.2.5)

C#

Utilities.ExceptionHandler.HandleSharePointException(ex);

5. Add the Utilities project output to our SharePoint solution.

Note: Simply adding a reference to the Utilities project does not package the assembly along with the rest of the SharePoint solution. You must do this explicitly.

a. Double click the Package.Package file.

b. Select the Advanced tab at the bottom of the screen.

c. Click Add >> Add Assembly from Project Output.

d. In the Source Project Dropdown, select Utilities.

e. Select OK.

Task 4 – Test the solution on-premises

In this task, you will deploy your solution to your on premise SharePoint installation and test the exception handling.

1. Deploy your solution to your local SharePoint instance by pressing F5.

2. Select Page.

3. Select Edit.

4. Select Insert.

5. Select Web Part.

6. Select Custom >> ExceptionGenerator Title.

7. Click Add.

8. From the ribbon, select Page >> Save and Close.

9. Click the Generate Exception button.

10. Navigate to <Your Local SharePoint Site>/Lab08/Help Desk (e.g. http://intranet.contoso.com/Lab08/Help Desk).

11. Confirm that a new issue was logged to the open issues. The title should be “Sample Exception <Timestamp>”. Click the ID link next to the new issue.

12. The details view of the issue will contain the details of the exception, including the stack trace and message of the exception.

Task 5 – Test the solution in SharePoint Online

In this task, you will save your on-premise published database locally and deploy to SharePoint Online.

1. Open Access. Make sure you still have the Issues database open.

2. Select File >> Save & Publish.

3. Select Save Database As.

4. Select Save As Local Database.

5. Select Save As.

6. Save the database as C:\%Office365TrainingKit%\Labs\5.2\Source\Before\Help Desk.accdb. The database is now disconnected from your local SharePoint site.

7. Select File >> Save & Publish

8. Select Publish to Access Services

9. In the Server URL textbox, enter <Your SharePoint Online URL>/Lab08 (e.g. https://contoso.sharepoint.com/Lab08)

10. In the Site Name textbox, enter Help Desk.

11. Select Publish to Access Services.

Note: Any new items created on premise will be carried over to SharePoint Online.

12. Open Visual Studio 2010.

13. In the Solution Explorer window, right-click on the Debugging project and select Package to package the project.

14. Open Internet Explorer and navigate to your SharePoint Online site (e.g https://contoso.sharepoint.com).

15. Click Site Actions and then select Site Settings.

16. Click the Solutions link in the Galleries section to view the site collection’s solution gallery.

17. Click on the Solutions tab in the ribbon and click the Upload Solution button.

18. Browse to the solution package at C:\ %Office365TrainingKit%\Labs\5.2\Source\After\Debugging\bin\Debug\Debugging.wsp and click Open.

19. In the Solution Gallery – Activate Solution, click the Activate button.

20. Browse to the root site of your SharePoint Online.

21. Click Site Actions >> Site Settings and choose Manage Site Collection Features.

22. Click the Activate button next to the Debugging Feature1 feature to activate the feature.

23. Navigate to the Lab08 home page.

24. Select Page.

25. Select Edit.

26. Select Insert.

27. Select Web Part.

28. Select Custom >> ExceptionGenerator Title.

29. Click Add.

30. Save and close the page by selecting Page >> Save & Close.

31. Click the button Generate Exception. This will generate a sample exception.

32. Navigate to <Your SharePoint Online Site Site>/Lab08/Help Desk.

33. Confirm that a new issue of was logged to the open issues. The title should be “Sample Exception <Timestamp>”. Click the link of the ID of the issue to see the details of the issue. The details of the issue will contain the details of the exception, including the stack trace and message of the exception.

Summary

In this lab, you learned how to publish a Microsoft Access database to SharePoint Online. By publishing your database to SharePoint, anyone with access to SharePoint Online can now interact with your Access database, without requiring that the user have Access installed. It also reduces the complexity of multiple sharing the same Access database file. Next, we explored the inner workings of the web that is created when you publish a database to SharePoint Online. Lastly, we added a row to an existing list and saw that the SharePoint site and Access database table were updated.