--------------------------------------------------------------------------------------------

---------------------------------------------------------------------------------------------

How to Asynchronously with Callback Invoke a .NET Web Service from .NET Managed Code

---------------------------------

Note: This outline assumes that on your machine you have installed Windows 2000, Visual Studio 6 (with Service Pack 4) followed by an installation of Visual Studio .NET 7 Beta 1

---------------------------------

Walkthrough Summary

Using Visual Studio 7, a Visual Basic (Managed) Web Service project is created. A IIS Virtual Directory is created for the Web Service and a <WebMethod()> member function is added to the Web Service class. Using WebServiceUtil.exe a Service Description (SDL) file and a client proxy class file (.vb) are generated. We show how to automate the above steps via a VS7 makefile utility project dependent of the Web Service project. A Visual Basic client project is created that imports the Web Service proxy class. We explicitly show how to use the generated proxy class methods to issue synchronous and asynchronous, with callback notification, SOAP calls into the WebMethod.

1. Using Visual Studio 7 (.NET Beta 1) create a Visual Basic Web Service named TestWebService.

1a. Create a new Web Service project.

Start Visual Studio 7. Click the 'File' menu item, select 'New / Project...'. Select 'Visual Basic Projects', click 'Web Service'. In the Name field type "TestWebService" (without quotes), in the Location field type "http://localhost". Click 'OK' in the 'New Project' dialog. Wait until the project is created and built.

2. (Optional) Create an IIS Virtual Directory which points to the TestWebService project directory.

2a. Close the Solution created in Step 1a.

Click the 'File' menu item and select 'Close Solution'.

2b. Create new folders.

Somewhere in your system create a new Folder (directory) that will contain your .NET solution, project and source files. Name the folder ManagedCode. Under ManagedCode create two subdirectories: ManagedCode\TestWebService and ManagedCode\Client.

2c. Stop IIS.

Start the Internet Services Manager MMC. Right click on the icon for your local computer and select 'Restart IIS ...'. Select 'Stop Internet Services on <Local Computer>' and click 'OK'. When the 'Shutting Down...' dialog is dismissed, in the IIS MMC click the 'Action' menu item and select 'Refresh' to make sure IIS is stopped (reply 'No' to any '... attempt to reconnect?' prompts); when done, the 'Default Web Site' icon should not show.

2d. Move your new Web Service directories to your designated location.

Using Windows Explorer, under C:\Inetpub\wwwroot (C: stands for the drive in which Windows 2000 is installed on your machine), cut the TestWebService directory tree and paste it to the ManagedCode folder you created in Step 2b.

2e. Restart IIS.

In the Internet Services Manager MMC. Right click on the icon for your local computer and select 'Restart IIS ...'. Select 'Start Internet Services on <Local Computer>' and click 'OK'; when done, the 'Default Web Site' icon should again show.

2f. Verify.

Left-click the 'Default Web Site' icon in the TreeView pane and verify that in the ListView pane, a TestWebService item does not exist.

2g. Create a new IIS Virtual Directory.

Right-click the 'Default Web Site' icon in the TreeView pane and select New / Virtual Driectory. To the 'Virtual Directory Creation Wizard' specify "TestWebService" (without quotes) for 'Alias' and for 'Directory' use the Browse button to point to your ManagedCode\TestWebService folder which now containts all source and project files. For 'Access Permissions' select all permissions and click 'Next', 'Yes' to confirm and 'Finish'.

3. (Optional) Create a new Visual Studio 7 Solution and add your TestWebService project to it.

3a. Create an empty Solution.

In Visual Studio 7, click the 'File' menu item, select 'New / Project...'. Select 'Visual Studio Solutions' and click 'Blank Solution'. In the Name field type "TestWebServiceSolution" (without quotes). For the 'Location' field use the Browse button to point to your ManagedCode folder created in Step 2b.

3b. Add your Web Service project to the Solution.

In the 'Solution Explorer' pane of Visual Studio 7, right-click on the 'Solution 'TestWebServiceSolution'' item and select 'Add / Existing Project...'. Point the 'Add Existing Project' dialog to your project file: "...\ManagedCode\TestWebService\TestWebService.vbproj". Close TestWebServiceSolution and Open it again to save all settings.

4. Add a test <WebMethod()> function to the Service1 class in your TestWebService project.

4a. Add the function to Service1.vb

In Visual Studio 7 'Solution Explorer' left-click on the TestWebService project item, then click on the 'Show All Files' icon of 'Solution Explorer'. Clicking on the '+' icons expand the tree under TestWebService until Service1.vb is visible. Right-click on Service1.vb and select 'Open'. In the Service1.vb window, add to class Service1 the following code defining a new member function:

Public Function <WebMethod()> TestFunc0(ByRef nRcvd As Integer, _

ByRef strRcvd As String) As String

nRcvd = 6

strRcvd = "aaaaa"

TestFunc0 = "bbbbb"

End Function

This code may be placed immediately above the 'Public Sub New()' function. Save all and build the TestWebService project.

5. Generate a Service Description (SDL) file for TestWebService.Service1

5a. Open a Command Window, 'Cmd.exe /k' in current directory: ...\ManagedCode\TestWebService\bin, and verify that it contains TestWebService.dll

5b. In the command window issue command: (without quotes)

'WebServiceUtil.exe /command:makeSDL /assembly:TestWebService.dll /base:http://localhost/TestWebService /out:.'

5c. You may view the generated Service1.sdl using Notepad.exe

6. Generate a Proxy class source file for TestWebService.Service1

6a. In the Command Window of Step 5, issue command: (without quotes)

'WebServiceUtil.exe /command:proxy /path:.\Service1.sdl /Language:vb /out:. /namespace:Service1Proxy /protocol:SOAP'

6b. You may view the generated Proxy class source file Service1.vb using Notepad.exe

7. (Optional) Project-Automate above Steps 5 and 6: Create a new Visual C++ Makefile project.

7a. Create a new Makefile project, Service1Proxy.

In Visual Studio 7, click the 'File' menu item, select 'New / Project...'. Select 'Visual C++ Projects / Utility Projects', and click 'Makefile Project' in the 'Templates:' pane. Make sure the 'Add to Solution' radio button is checked. In the Name field type "Service1Proxy" (without quotes), in the Location field Browse to your '...\ManagedCode\TestWebService' folder so that the project will be created in folder '...\ManagedCode\TestWebService\Service1Proxy'. Click 'OK' in the 'New Project' dialog.

7b. Edit Makefile project settings.

In the 'Makefile Application Wizard' dialog, 'Application Settings' tab, clear the 'Output:' field and fill in the other fields as follows:

Build Command Line: nmake.exe /f Service1Proxy.mk

Clean Commands: nmake.exe /f Service1Proxy.mk clean

Rebuild Command Line: nmake.exe /a /f Service1Proxy.mk

Click 'Finish'.

7c. Add a source file Service1Proxy.mk to your Service1Proxy project.

In 'Solution Explorer' right-click the 'Source Files' icon under project Service1Proxy. From the drop-down menu tree select 'Add / Add New Item ...'. In the 'Add New Item - ...' dialog select 'Visual C++ / Utility' in the 'Categories:' pane and 'Text File (.txt)' in the 'Templates:' pane. In the 'Name:' field rename the file to "Service1Proxy.mk" (without quotes). Click 'Open' to dismiss the dialog.

7d. Edit makefile Service1Proxy.mk

In accord with the results of Steps 5 and 6, copy/paste the following text into Service1Proxy.mk: (note: keep the blank lines, they are meaningful to nmake.exe)

# Service1Proxy.mk text begin

# macros

indir = ..\bin

outdir = ..\bin

basehttp = http://localhost/TestWebService

namespc = Service1Proxy

proxylanguage = vb

proxyprotocol = SOAP

# target-dependencies

all : $(outdir)\Service1.sdl $(outdir)\Service1.vb

$(outdir)\Service1.sdl : $(indir)\TestWebService.dll

WebServiceUtil.exe /command:makeSDL /assembly:$(indir)\TestWebService.dll /base:$(basehttp) /out:$(outdir)

$(outdir)\Service1.vb : $(outdir)\Service1.sdl

WebServiceUtil.exe /command:proxy /path:$(outdir)\Service1.sdl /Language:$(proxylanguage) /out:$(outdir) /namespace:$(namespc) /protocol:$(proxyprotocol)

clean :

del $(outdir)\Service1.sdl

del $(outdir)\Service1.vb

# Service1Proxy.mk text end

Close Service1Proxy.mk .

7e. Build project Service1Proxy.

In Visual Studio 7, build your TestWebService project and verify that '...\ManagedCode\TestWebService\bin\TestWebService.dll' exists. Build the new Service1Proxy project and verify that Service1.sdl and Service1.vb have been created in the bin directory. You may also wish to verify that Build, Clean and Rebuild operations on project Service1Proxy perform as expected.

7f. Modify Project Dependencies and set a new StartUp project.

In the 'Solution Explorer' window right-click the icon for project Service1Proxy, select 'Project Dependencies...' and in the 'Project Dependencies' dialog put a check mark next to the 'TestWebService' item. Click OK to dismiss the dialog. In the 'Solution Explorer' window right-click the icon for project Service1Proxy and click 'Set as StartUp Project'. Save all.

8. Create a .NET Managed Code Client Application.

8a. Add to your Solution a new Visual Basic Windows Application project.

In Visual Studio 7, click the 'File' menu item, select 'New / Project...'. Select 'Visual Basic Projects', and click 'Windows Application' in the 'Templates:' pane. Make sure the 'Add to Solution' radio button is checked. In the Name field leave "WindowsApplication1" (without quotes), in the Location field Browse to your '...\ManagedCode\Client' folder so that the project will be created in folder '...\ManagedCode\Client\WindowsApplication1'. Click 'OK' in the 'New Project' dialog.

8b. Add the generated proxy source file, 'bin\Service1.vb' to the client WindowsApplication1 project.

In 'Solution Explorer' right-click the 'WindowsApplication1'. From the drop-down menu tree select 'Add / Add Existing Item ...'. Point the 'Add Existing Item - ...' dialog to the generated Service1 proxy file '...\ManagedCode\TestWebService\bin\Service1.vb' and click 'Open' to dismiss the dialog.

8c. Modify Project Dependencies and set a new StartUp project.

In the 'Solution Explorer' window right-click the icon for project WindowsApplication1, select 'Project Dependencies...' and in the 'Project Dependencies' dialog put a check mark next to the 'Service1Proxy' item. Click OK to dismiss the dialog. In the 'Solution Explorer' window right-click the icon for project WindowsApplication1 and click 'Set as StartUp Project'. Save all.

8d. Activate the Controls Toolbox.

In Visual Studio 7, click the 'View' menu item, select 'Toolbox'.

8e. Add Controls to WindowsApplication1.Form1

Using the toolbox of Step 8d, add the following controls to Form1:

----------------------------------------------------------

Name Caption/Text Control Type

Button1 Synchronous Call System.Winforms.Button

Button2 Asynchronous Call System.Winforms.Button

Label1 Returned Value System.Winforms.Label

Label2 Returned Param1 System.Winforms.Label

Label3 Returned Param2 System.Winforms.Label

----------------------------------------------------------

Once the controls are positioned in Form1, in turn click each control, press <F4> (to access the Properties window) and verify that all controls have their 'Visible' property set to 'True'. Save All and Build project WindowsApplication1.

8f. Import namespace Service1Proxy into Form1.

In the 'Solution Explorer' window, under project WindowsApplication1 right-click the Form1.vb icon and from the drop-down menu click 'View Code' to edit Form1.vb code. At the bottom of the 'Imports' list add the snippet:

'----- Added code line begin

Imports WindowsApplication1.Service1Proxy

'----- Added code line end

Save All.

8g. Synchronous Call Client Code.

Add code to the Button1 Click event handler: Sub Button1_Click().

In the 'Solution Explorer' window, under project WindowsApplication1 double-click the Form1.vb icon for a design-time view of Form1. In the 'Form1[Design]' pane double-click Button1 ("Synchronous Call") to open the code editor for event handler Sub Button1_Click(). Paste the following code segment to the body of Sub Button1_Click():

'----- Paste into Sub Button1_Click() begin

label1.Text = ""

label2.Text = ""

label3.Text = ""

Dim refService1 As Service1

refService1 = New Service1()

debug.Assert(Not refService1 Is Nothing)

Dim strRet As String

Dim nParam1 As Integer

Dim strParam2 As String

nParam1 = 0

strParam2 = ""

strRet = refService1.TestFunc0(nParam1, strParam2)

label1.Text = strRet

label2.Text = str(nParam1)

label3.Text = strParam2

'----- Paste into Sub Button1_Click() end

'Save All' and build project WindowsApplication1.

8h. Test the Synchronous Call to Web Service1.

In Visual Studio 7, click the 'Debug' menu item and select 'Start'. When your Form1 window shows, click the 'Synchronous Call' button. Alternatively, you may wish to set a breakpoint in Sub Button1_Click(), click the 'Synchronous Call' button, and step through the call using the debugger.

8i. Asynchronous Call Callback Client Code.

In the 'Solution Explorer' window, under project WindowsApplication1 right-click the Form1.vb icon and from the drop-down menu click 'View Code' to edit Form1.vb code. Add to the top of the Class Form1 code, immediately above the 'Public Sub New()' declaration, the following snippet:

'----- Paste Asynchronous callback and supporting declarations begin

Dim refService1 As Service1 ' ref to the proxy

Public Sub MyCallBackForTestFunc0(ByVal ar As IAsyncResult)

Dim strRet As String

Dim nParam1 As Integer

Dim strParam2 As String

If Not ar.IsCompleted Then

debug.assert(False)

End If

debug.Assert(Not refService1 Is Nothing)

strRet = refService1.EndTestFunc0(ar, nParam1, strParam2)

label1.Text = strRet

label2.Text = str(nParam1)

label3.Text = strParam2

End Sub

'----- Paste Asynchronous callback and supporting declarations end

'Save All' and build project WindowsApplication1.

8j. Asynchronous Call Client Code.

Add code to the Button2 Click event handler: Sub Button2_Click().

In the 'Solution Explorer' window, under project WindowsApplication1 double-click the Form1.vb icon for a design-time view of Form1. In the 'Form1[Design]' pane double-click Button2 ("Asynchronous Call") to open the code editor for event handler Sub Button2_Click(). Paste the following code segment to the body of Sub Button2_Click():

'----- Paste into Sub Button2_Click() begin

label1.Text = ""

label2.Text = ""

label3.Text = ""

If refService1 Is Nothing Then

refService1 = New Service1()

End If

debug.Assert(Not refService1 Is Nothing)

Dim cb As AsyncCallback

cb = New AsyncCallback(AddressOf MyCallBackForTestFunc0)

debug.Assert(Not cb Is Nothing)

Dim refAsyncResult As IAsyncResult

refAsyncResult = refService1.BeginTestFunc0(0, "", cb, Nothing)

debug.Assert(Not refAsyncResult Is Nothing)

'----- Paste into Sub Button2_Click() end

'Save All' and build project WindowsApplication1.

8k. Test the Asynchronous Call to Web Service1.

In Visual Studio 7, click the 'Debug' menu item and select 'Start'. When your Form1 window shows, click the 'Aynchronous Call' button. Alternatively, you may wish to set breakpoints in 'Sub Button2_Click()' and 'Sub MyCallBackForTestFunc0()', click the 'Asynchronous Call' button, and step through the call using the debugger.

Done.

Rafael Pena

rpenaphd@worldnet.att.net

2/24/2001

Keywords: HowTo, Walkthrough

How to Asynchronously with Callback Invoke a .NET Web Service from .NET Managed Code ---------------------------------

How to Asynchronously with Callback Invoke a .NET Web Service from .NET Managed Code

---------------------------------