Share via


How to: Use the CloseWorkbook Method Call Asynchronously

Applies to: SharePoint Server 2010

When you are using Excel Web Services, it is good practice to close the workbook by calling the CloseWorkbook method if you are finished using the session. This closes the session and allows Excel Services to free resources in a predictable manner. This could potentially improve your server performance and robustness.

However, any Web service call takes time. Depending on the way your server is installed, the way that you access it, and how much stress the server is under, the call can take anywhere between 50 milliseconds to 500 milliseconds. It can also take longer, but only if your server is under severe stress.

Because a failed CloseWorkbook method call is not actionable, you do not need to wait for it to finish to see whether it succeeds. Because of this, you can usually make the call asynchronously and save some operation time.

Note

If your application makes some calls to Excel Services and then exits, you may want to close a workbook synchronously instead of asynchronously. In this case, you call the CloseWorkbook method instead of the CloseWorkbookAsync method. The reason is if you immediately exit the process after issuing an asynchronous call, there is a good chance the call might not get through.

To close the workbook asynchronously, you must do two things:

  • Make sure you do not dispose the Excel Web Services proxy class—if you do, non-Excel Services exceptions may occur.

  • Call the CloseWorkbookAsync method instead of the CloseWorkbook method. The signature for the CloseWorkbookAsync method is:

    public void CloseWorkbookAsync(string sessionId)
    
    Public Sub CloseWorkbookAsync(ByVal sessionId As String)
    End Sub
    

You don't have to implement the event that is called when the CloseWorkbookAsync method is called.

You can find the signature in the "Reference.cs" file in your project "Web References" directory.

Note

You can find the CloseWorkbookAsync method in the proxy class that is generated when you add a Web reference using Microsoft Visual Studio 2005. If you are using Visual Studio 2003, you call the BeginCloseWorkbook method to close a workbook asynchronously instead.

Calling the CloseWorkbookAsync method or BeginCloseWorkbook method means the call to close a workbook will be executed asynchronously and not cost your application any significant amount of time.

Example

The following example shows how to close a workbook asynchronously using Visual Studio 2005.

using System;
using SampleApplication.ExcelWebService;
using System.Web.Services.Protocols;
namespace SampleApplication
{
    class Class1
    {
        [STAThread]
        static void Main(string[] args)
        {            
            // Instantiate the Web service 
            // and create a status array object.
            ExcelService es = new ExcelService();
            Status[] outStatus;

            string sheetName = "Sheet1";
            // TODO: change the workbook path to 
            // point to workbook in a trusted location
            // that you have access to. 
            string targetWorkbookPath = 
             "http://myserver02/example/Shared%20Documents/Book1.xlsx";

            // Set credentials for requests.
            es.Credentials = 
                System.Net.CredentialCache.DefaultCredentials;
            
            try
            {
                // Call open workbook, and point to the trusted   
                // location of the workbook to open.
                string sessionId = es.OpenWorkbook(targetWorkbookPath, 
                    "en-US", "en-US", out outStatus);
                // Call the GetCell method 
                // to retrieve a value from a cell.
                // The cell is in the first row and ninth column.
                object[] rangeResult2 = xlservice.GetCell(sessionId, 
                    sheetName, 0, 8, false, out outStatus);
 
                // Close the workbook asynchronously. 
                // This also closes session.
                es.CloseWorkbookAsync(sessionId);
            }
            catch (SoapException e)
            {
                Console.WriteLine("SOAP Exception Message: {0}", 
                   e.Message);
                Console.WriteLine("SOAP Exception Error Code: {0}", 
                   e.SubCode.Code.Name);
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception Message: {0}", e.Message);
            }
            // Console.ReadLine();
        }
    }
}
 
Imports System
Imports SampleApplication.ExcelWebService
Imports System.Web.Services.Protocols
Namespace SampleApplication
    Friend Class Class1
        <STAThread> _
        Shared Sub Main(ByVal args() As String)
            ' Instantiate the Web service 
            ' and create a status array object.
            Dim es As New ExcelService()
            Dim outStatus() As Status

            Dim sheetName As String = "Sheet1"
            ' TODO: change the workbook path to 
            ' point to workbook in a trusted location
            ' that you have access to. 
            Dim targetWorkbookPath As String = "http://myserver02/example/Shared%20Documents/Book1.xlsx"

            ' Set credentials for requests.
            es.Credentials = System.Net.CredentialCache.DefaultCredentials

            Try
                ' Call open workbook, and point to the trusted   
                ' location of the workbook to open.
                Dim sessionId As String = es.OpenWorkbook(targetWorkbookPath, "en-US", "en-US", outStatus)
                ' Call the GetCell method 
                ' to retrieve a value from a cell.
                ' The cell is in the first row and ninth column.
                Dim rangeResult2() As Object = xlservice.GetCell(sessionId, sheetName, 0, 8, False, outStatus)

                ' Close the workbook asynchronously. 
                ' This also closes session.
                es.CloseWorkbookAsync(sessionId)
            Catch e As SoapException
                Console.WriteLine("SOAP Exception Message: {0}", e.Message)
                Console.WriteLine("SOAP Exception Error Code: {0}", e.SubCode.Code.Name)
            Catch e As Exception
                Console.WriteLine("Exception Message: {0}", e.Message)
            End Try
            ' Console.ReadLine();
        End Sub
    End Class
End Namespace

Robust Programming

Make sure that you add a Web reference to an Excel Web Services site that you have access to. Change the using SampleApplication.ExcelWebService; statement to point to the Web service site that you are referencing.

In addition, make changes to the workbook path, sheet name, and so on, as appropriate.

See Also

Tasks

Walkthrough: Developing a Custom Application Using Excel Web Services

How to: Catch Exceptions

How to: Trust a Location

How to: Save from Excel Client to the Server

How to: Use the SubCode Property to Capture Error Codes

Concepts

Accessing the SOAP API

Excel Services Alerts

Excel Services Known Issues and Tips

Loop-Back SOAP Calls and Direct Linking