ASPNET Web Service
Content
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Abstract
By Patrick Barnes Before the advent of Web services, other technologies and architectures existed that allowed applications to remotely call procedures exposed by other applications, typically using the TCP/IP protocol. You have undoubtedly heard of Microsoft's version of this technology, called Component Object Model* (COM*), and subsequently Distributed COM* (DCOM*). Common Object Request Broker Architecture* (CORBA*) is a competitor of COM, developed by a consortium of vendors under the aegis of the Object Management Group. Although these technologies were a breakthrough in distributed computing and served such ends well for at least five years, there were many limitations. Concerning DCOM, its two main disadvantages were: Microsoft-only: DCOM works properly only with binaries written with Microsoft languages and running on Microsoft platforms. Not Suitable for the Internet: DCOM was designed to use the TCP/IP protocol over a LAN or WAN. Firewalls present a serious problem, and performance is often poor and unreliable. Web services solve many of the problems common to DCOM. A Web service is a unit of code that publicly exposes its functionality as a URL-addressable resource. As such, any client application that conforms to open Web standards such as HTTP and the Simple Object Access Protocol (SOAP)—the main message formatting protocol, as opposed to HTTP, which is a message transmission protocol—can call a Web service, initiate a procedure, and even retrieve data in the form of an XML document. Thus, Web services take care of the two problems with DCOM and other distributed programming technologies: Non-proprietary: Open standards are governed by the World Wide Web Consortium (www.W3C.org*) and other grassroots organizations. All communication and data formatting protocols are non-proprietary, detaching this form of remote procedure calling from specific languages and platforms. Internet-savvy: Web services were designed specifically for use over the Internet via HTTP. This article shows you how to build and consume a basic ASP .NET Web service. It focuses on the steps required to build the Web service and client application that consumes it. For more theoretical or in-depth information about Web services, see the list of resources at the end of this article. Assumptions and Requirements This article assumes no prior knowledge of Web services, Visual Studio .NET*, or Visual Basic .NET*. The Web Service is built using Visual Studio .NET, although the IDE is not required to build .NET Web services. You could write the code and compile it using the Visual Basic compiler from the command line. However, this article assumes you are using Visual Studio .NET and thus makes no accommodations for other situations. Finally, you will need access to the Northwind* database shipped with Microsoft SQL Server* and the Microsoft Data Engine* (MSDE).
Creating a Web Service Project in Visual Studio .NET
Follow these steps show to create an ASP .NET Web service project in Visual Studio .NET. 1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET. 2. Click New Project. 3. Select Visual Basic Projects in the Project Types pane.
1 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
4. Select ASP.NET Web Service in the Templates pane. 5. In the Location box, enter the name of the Web server with the name of the project, http://ServerName (or Localhost)/intel_wsNWProducts. See Figure 1.
Figure 1. Creating the Project in Visual Studio .NET. 6. Click OK. The intel_wsNWProducts project is created and added to a Solution by the same name. Service1.asmx is open in design view. 7. Click the design surface and press F4 to access the Web service page's Properties window. 8. Set the Name property of Service1 to ProductsService. 9. In Solution Explorer, right-click the Service1.asmx file, select Rename, and rename the file Products.asmx to match the service name.
Exposing a Web Method
Functions and subroutines that you want to expose to the public over HTTP are essentially no different than non-Web service methods. The only difference is the use of the <WebMethod> attribute, as you will see. The method you will build for this article's Web service allows anyone to retrieve a list of products from the Northwind database by product category. The user types in a CategoryID, which is forwarded to the Web service. The Web service returns the products in that category. (If no category is entered by the user, all products are returned.)
2 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
1. In the Code Editor window right-click on Products.asmx.vb and select View Code. 2. Replace the commented lines with the following shell of a function that returns a DataSet:
Public Function GetProducts(ByVal strCategoryID As Int32) As DataSet End Function
In the next step you will add an Imports statement that lets you use shorthand notation when accessing classes in the imported namespace. A namespace is simply a logical grouping of related .NET types, such as classes, interfaces, enums, structures, and so forth. This makes it easier to work with the Base Class Library and also prevents type name conflicts. You can always access the type using a fully qualified name like this: System.Data.SqlClient.SqlConnection. The advantage of an Imports statement, however, is that you can simplify and lighten your code with the use of shorthand dot notation. Thus, if you import the System.Data.SqlClient namespace, in your code you need only type SqlConnection. 3. At the top of the page of code add the following: Imports System.Data.SqlClient Classes in the SqlClient namespace classes are optimized for use with SQL Server. If you were working with another database, you could use classes in the System.Data.OleDb. 4. Create a SqlConnection object. Add the following to the function (adjust the connection string for your setup):
Dim cn As New SqlConnection("server=(localhost);uid=sa;pwd=;database=northwind")
5. Create a SqlCommand object. This object executes SQL statements against a SQL Server database. You are passing in two arguments, the SQL statement that, at this point, returns all of the products, as well as the newly created Connection object. Add this code:
Dim cmd As New SqlCommand("select * from products",cn)
6. To support filtering the products by CategoryID, add the next few lines of code. The SQL has been built this way so that if the user doesn't enter a CategoryID, the Web service assumes that he or she wants to view all products:
If strCategoryID <> "" Then cmd.CommandText &= " where CategoryID = " & strCategoryID End If
7. Create a SqlDataAdapter object, which takes the SqlCommand object as an argument and is responsible for filling the DataSet that is returned by this method. Add this line of code:
3 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Dim da As New SqlDataAdapter(cmd) 8. These last few lines of code complete the inner workings of the Web method. Add the following lines of code to create a new empty DataSet object, pass it to the SqlDataAdapter for filling, and then return the filled DataSet to the calling function:
Dim ds As New DataSet() da.Fill(ds) Return ds
9. The function is now complete, but it is not yet exposed as a public Web method. For this all you need to do is mark up the function with the <WebMethod()> attribute: <WebMethod()> Public Function GetProducts... You can also pass in a description of the Web method that will appear on the Framework-generated pages. You will be introduced to this in the next section. 10. Pass a description of the Web method as follows: <WebMethod(Description:="This method returns a DataSet containing products from the Northwind database. Not passing an argument results in all products being returned. Or you may pass a CategoryID to view only products in that category.")>
Running and Testing the Web Service
The .NET Framework makes it easy to run and test a Web service by automatically generating a set of test and information pages when you access a .NET Web service. 1. Press F5 to build and run the Web service in debug mode. After 5 or more seconds (depending on your machine, database connection, and so forth), the main Web service page created by the Framework opens in your browser.
Figure 2. The Main Web Service Page. The main Web service page contains general information about a Web service, lists the methods it exposes, and provides a link to its WSDL document. WSDL is an XML document that describes the Web service's public interface. Examining the WSDL document enables you to build a client application that can call the Web service and consume the data it returns. It is a kin to the old COM interface ontracts. 2. Click the GetProducts link to access the test page for this Web method.
4 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 3. Test Page for the Web Method. All test pages have an Invoke button. Because this Web method takes one argument, CategoryID, the Framework also adds a Textbox to enter a value before invoking the method. 3. Click Invoke without entering a CategoryID. A second browser window opens and displays the XML representation of the DataSet returned by this Web method. The actual data is preceded by the schema representation of the DataSet:
- <xs:schema id="NewDataSet" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata=" urn:schemas-microsoft-com:xml-msdata">
- <xs:element name="NewDataSet" msdata:IsDataSet="true"> - <xs:complexType> - <xs:choice maxOccurs="unbounded"> - <xs:element name="Table"> - <xs:complexType> - <xs:sequence> <xs:element name="ProductID" type="xs:int" minOccurs="0" /> <xs:element name="ProductName" type="xs:string" minOccurs="0" /> <xs:element name="SupplierID" type="xs:int" minOccurs="0" /> <xs:element name="CategoryID" type="xs:int" minOccurs="0" />
5 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
<xs:element name="QuantityPerUnit" type="xs:string" minOccurs="0" /> <xs:element name="UnitPrice" type="xs:decimal" minOccurs="0" /> <xs:element name="UnitsInStock" type="xs:short" minOccurs="0" /> <xs:element name="UnitsOnOrder" type="xs:short" minOccurs="0" /> <xs:element name="ReorderLevel" type="xs:short" minOccurs="0" /> <xs:element name="Discontinued" type="xs:boolean" minOccurs="0" /> </xs:sequence> </xs:complexType> </xs:element> </xs:choice> </xs:complexType> </xs:element> </xs:schema> This code shows data for a single product:
- <NewDataSet xmlns=""> - <Table diffgr:id="Table1" msdata:rowOrder="0"> <ProductID>1</ProductID> <ProductName>Chai</ProductName> <SupplierID>1</SupplierID> <CategoryID>1</CategoryID> <QuantityPerUnit>10 boxes x 20 bags</QuantityPerUnit> <UnitPrice>18</UnitPrice> <UnitsInStock>39</UnitsInStock> <UnitsOnOrder>0</UnitsOnOrder> <ReorderLevel>10</ReorderLevel> <Discontinued>false</Discontinued> </Table>
4. Close the browser containing the XML data. 5. In the strCategoryID field type "2" and click Invoke. 6. Scroll through the results, verifying that only those products with CategoryID = 2 are displayed. 7. Close both browser windows.
Creating an ASP .NET Web Application to Consume the Web Service
6 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
You have built the Web service and are now ready to build a client application to consume it. Follow these steps to add an ASP .NET Web Application to your existing Solution. 1. In the Solution Explorer, right-click Solution 'intel_wsNWProducts', point to Add, and then click New Project. 2. Select Visual Basic Projects in the Project Types pane. 3. Select ASP.NET Web Application in the Templates pane. 4. In the Location field type "http:// localhost/intel_wsNWProductsClient". 5. Click OK. The Intel_wsNWProductsClient project is added to the Solution.
Adding Controls to a Web Form
Now you can build a Web Form containing a Textbox and Button that will allow the user to enter a CategoryID and invoke the Web service by clicking the Button. 1. You should see a blank design surface for WebForm1.aspx. (If you are not in Design View, click the Design tab below the Code Editor window.) 2. Right-click the design surface and select Properties. In the Page Layout drop-list select FlowLayout and click OK. FlowLayout is easier to use for designing and positioning form controls than the default GridLayout. 3. Click the design surface and type "CategoryID:". 4. Press CTRL + ALT + T to open the Toolbox. From the Web Forms group select and drag a Textbox to the design surface, placing it to the right of the text you just typed. 5. Press F4 to access the Textbox properties. In the Properties window, change the Columns property to 1. 6. From the Toolbox, select and drag a Button to the design surface, placing it to the right of the Textbox. 7. Press F4 to access the Button properties. In the Properties window, change the Text property to "Get Products". 8. Press Enter to move the cursor to the next line on the design surface. 9. From the Toolbox, select and drag a DataGrid to the design surface. 10. Press F4 to access the DataGrid properties. In the Properties window, below all of the properties click the Auto Format link. Select any Scheme you like and click OK.
7 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 4. Setting Auto Format Schemes.
Adding a Web Reference
If you have experience building applications, you are undoubtedly familiar with the concept of a reference. A reference registers a binary with the development environment so that its members can be accessed programmatically. In fact, when Visual Studio .NET created both the Web service and Web application projects, it automatically included references to the most common .NET assemblies for building each type of project. You can see a list of these assemblies by expanding References in the Solution Explorer. The concept of a Web reference is very similar. The difference is, of course, that the binary you are referencing is remote. It could be thousands of miles away on another server, hosted by a company with which you have no association. As you will see, a Web reference is merely a pointer to the Web service's WSDL document. As mentioned earlier, the WSDL document describes the Web service's public interface. The .NET Framework processes this document and generates a proxy class, which becomes like the other binaries that are locally referenced in your project. It "stands in the place of" the Web service class, allowing you to use its API as if the Web service were local instead of remote. 1. In the Solution Explorer, right-click References under Intel_wsNWProductsClient and select Add Web Reference. 2. In the Address field type "http://localhost/intel_wsNWProducts/Products.asmx". This is the URL to the main Web service page you saw earlier containing information about your Web service and a link to test the Web method. 3. Press Enter. The page appears in the left pane.
8 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 6. Adding a Web Reference. 4. Click Add Reference. Visual Studio .NET will now access the Web service's WSDL document over HTTP and generate a proxy class for you. Notice that a Web References node appears in the Solution Explorer, with a child localhost node. 5. It is worthwhile to examine briefly what is contained in the proxy class. In the Solution Explorer, click the View All Files icon. 6. Expand Web References | localhost | Reference.map. 7. Right-click Reference.vb and select View Code. Examine the proxy class code. Although it is beyond the scope of this article to discuss the code in detail, consider the following noteworthy points. The proxy class derives from System.Web.Services.Protocols.SoapHttpClientProtocol. This class takes care of the low-level Web service connectivity, SOAP messaging and deserialization. Much of its functionality is inherited from other classes in the same namespace. The inherited Url property maintains a reference to the Web service address. Proxy methods have been created for both the synchronous and asynchronous calling of the Web service's methods. When the XML is received back from the Web service, the proxy class takes care of deserializing it—reconstructing the DataSet object from the XML based on the schema information included in the XML stream. 8. Close Reference.vb.
Adding Code to Call the Web Method
With the Web Form controls in place, you are ready to add the code needed to invoke the Web method and display the results in the DataGrid. 1. On the design surface for WebForm1.aspx, double-click the Button to create a Click event handler. 2. In the event handler, add the following code, which creates an instance of the Web service proxy class and calls the GetProducts proxy method:
9 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Dim ws As New localhost.ProductsService() DataGrid1.DataSource = ws.GetProducts(TextBox1.Text) DataGrid1.DataBind()
This is a surprisingly small amount of code, thanks entirely to the proxy class created for you. All of the complex issues involved with connecting to a Web service, creating and receiving SOAP-formatted messages, and deserializing XML are taken care of for you behind the scenes.
Running the Client Application
Running the Web application client from within Visual Studio .NET requires that you first set the startup project and start page. 1. In the Solution Explorer, right-click the intel_wsNWProductsClient project and select Set as Startup Project. 2. Right-click WebForm1.aspx and select Set As Start Page. 3. Press F5 to build and run the Solution in debug mode. 4. When the page appears in the browser, click Get Products. After a brief delay due to the Web service being "just in time" (JIT) compiled by the .NET runtime (this happens only the first time the Web service is invoked), the DataGrid displays with information about all of the Products. 5. In the Textbox type "2" and click Get Products. The DataGrid shows only those Products in the second category.
10 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 7. The DataGrid. 6. Close the browser.
Conclusion and Resources
Entire books have been written on Web services. Yet with this brief hands-on introduction, you should now have a basic understanding of the following: What a Web service is. Why it solves many of the key problems common to previous distributed programming technologies. How to build a Web service using Visual Studio .NET. How to build a client ASP .NET Web application to consume it. You're ahead of the game! Resources The following Web-based resources will be help you learn more about this incredible new technology that is changing the face of the Internet forever. Microsoft Developer Network (MSDN) Main Web Services Page* "XML Web Service Basics"* "Using Web Services Instead of DCOM"* "Visual Studio .NET: Build Web Applications Faster and Easier Using Web Services and XML"*
11 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
"Creating a .NET Web Service"*
About the Author
Patrick Barnes is a freelance Web application developer, author and consultant located in Cedar Rapids, Iowa. He specializes in n-tier development using ASP .NET, Visual Basic* .NET, SQL Server*, and XML.
The information, opinions, and recommendations in this column are provided by the Author, Patrick Barnes. Intel and its subsidiaries do not necessarily endorse or represent the accuracy of the Author's information, opinions or recommendations, and any reliance upon the Author's statements is solely at your own risk.
12 of 12
11/7/05 20:28
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Abstract
By Patrick Barnes Before the advent of Web services, other technologies and architectures existed that allowed applications to remotely call procedures exposed by other applications, typically using the TCP/IP protocol. You have undoubtedly heard of Microsoft's version of this technology, called Component Object Model* (COM*), and subsequently Distributed COM* (DCOM*). Common Object Request Broker Architecture* (CORBA*) is a competitor of COM, developed by a consortium of vendors under the aegis of the Object Management Group. Although these technologies were a breakthrough in distributed computing and served such ends well for at least five years, there were many limitations. Concerning DCOM, its two main disadvantages were: Microsoft-only: DCOM works properly only with binaries written with Microsoft languages and running on Microsoft platforms. Not Suitable for the Internet: DCOM was designed to use the TCP/IP protocol over a LAN or WAN. Firewalls present a serious problem, and performance is often poor and unreliable. Web services solve many of the problems common to DCOM. A Web service is a unit of code that publicly exposes its functionality as a URL-addressable resource. As such, any client application that conforms to open Web standards such as HTTP and the Simple Object Access Protocol (SOAP)—the main message formatting protocol, as opposed to HTTP, which is a message transmission protocol—can call a Web service, initiate a procedure, and even retrieve data in the form of an XML document. Thus, Web services take care of the two problems with DCOM and other distributed programming technologies: Non-proprietary: Open standards are governed by the World Wide Web Consortium (www.W3C.org*) and other grassroots organizations. All communication and data formatting protocols are non-proprietary, detaching this form of remote procedure calling from specific languages and platforms. Internet-savvy: Web services were designed specifically for use over the Internet via HTTP. This article shows you how to build and consume a basic ASP .NET Web service. It focuses on the steps required to build the Web service and client application that consumes it. For more theoretical or in-depth information about Web services, see the list of resources at the end of this article. Assumptions and Requirements This article assumes no prior knowledge of Web services, Visual Studio .NET*, or Visual Basic .NET*. The Web Service is built using Visual Studio .NET, although the IDE is not required to build .NET Web services. You could write the code and compile it using the Visual Basic compiler from the command line. However, this article assumes you are using Visual Studio .NET and thus makes no accommodations for other situations. Finally, you will need access to the Northwind* database shipped with Microsoft SQL Server* and the Microsoft Data Engine* (MSDE).
Creating a Web Service Project in Visual Studio .NET
Follow these steps show to create an ASP .NET Web service project in Visual Studio .NET. 1. Click Start, point to Programs, point to Microsoft Visual Studio .NET, and then click Microsoft Visual Studio .NET. 2. Click New Project. 3. Select Visual Basic Projects in the Project Types pane.
1 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
4. Select ASP.NET Web Service in the Templates pane. 5. In the Location box, enter the name of the Web server with the name of the project, http://ServerName (or Localhost)/intel_wsNWProducts. See Figure 1.
Figure 1. Creating the Project in Visual Studio .NET. 6. Click OK. The intel_wsNWProducts project is created and added to a Solution by the same name. Service1.asmx is open in design view. 7. Click the design surface and press F4 to access the Web service page's Properties window. 8. Set the Name property of Service1 to ProductsService. 9. In Solution Explorer, right-click the Service1.asmx file, select Rename, and rename the file Products.asmx to match the service name.
Exposing a Web Method
Functions and subroutines that you want to expose to the public over HTTP are essentially no different than non-Web service methods. The only difference is the use of the <WebMethod> attribute, as you will see. The method you will build for this article's Web service allows anyone to retrieve a list of products from the Northwind database by product category. The user types in a CategoryID, which is forwarded to the Web service. The Web service returns the products in that category. (If no category is entered by the user, all products are returned.)
2 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
1. In the Code Editor window right-click on Products.asmx.vb and select View Code. 2. Replace the commented lines with the following shell of a function that returns a DataSet:
Public Function GetProducts(ByVal strCategoryID As Int32) As DataSet End Function
In the next step you will add an Imports statement that lets you use shorthand notation when accessing classes in the imported namespace. A namespace is simply a logical grouping of related .NET types, such as classes, interfaces, enums, structures, and so forth. This makes it easier to work with the Base Class Library and also prevents type name conflicts. You can always access the type using a fully qualified name like this: System.Data.SqlClient.SqlConnection. The advantage of an Imports statement, however, is that you can simplify and lighten your code with the use of shorthand dot notation. Thus, if you import the System.Data.SqlClient namespace, in your code you need only type SqlConnection. 3. At the top of the page of code add the following: Imports System.Data.SqlClient Classes in the SqlClient namespace classes are optimized for use with SQL Server. If you were working with another database, you could use classes in the System.Data.OleDb. 4. Create a SqlConnection object. Add the following to the function (adjust the connection string for your setup):
Dim cn As New SqlConnection("server=(localhost);uid=sa;pwd=;database=northwind")
5. Create a SqlCommand object. This object executes SQL statements against a SQL Server database. You are passing in two arguments, the SQL statement that, at this point, returns all of the products, as well as the newly created Connection object. Add this code:
Dim cmd As New SqlCommand("select * from products",cn)
6. To support filtering the products by CategoryID, add the next few lines of code. The SQL has been built this way so that if the user doesn't enter a CategoryID, the Web service assumes that he or she wants to view all products:
If strCategoryID <> "" Then cmd.CommandText &= " where CategoryID = " & strCategoryID End If
7. Create a SqlDataAdapter object, which takes the SqlCommand object as an argument and is responsible for filling the DataSet that is returned by this method. Add this line of code:
3 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Dim da As New SqlDataAdapter(cmd) 8. These last few lines of code complete the inner workings of the Web method. Add the following lines of code to create a new empty DataSet object, pass it to the SqlDataAdapter for filling, and then return the filled DataSet to the calling function:
Dim ds As New DataSet() da.Fill(ds) Return ds
9. The function is now complete, but it is not yet exposed as a public Web method. For this all you need to do is mark up the function with the <WebMethod()> attribute: <WebMethod()> Public Function GetProducts... You can also pass in a description of the Web method that will appear on the Framework-generated pages. You will be introduced to this in the next section. 10. Pass a description of the Web method as follows: <WebMethod(Description:="This method returns a DataSet containing products from the Northwind database. Not passing an argument results in all products being returned. Or you may pass a CategoryID to view only products in that category.")>
Running and Testing the Web Service
The .NET Framework makes it easy to run and test a Web service by automatically generating a set of test and information pages when you access a .NET Web service. 1. Press F5 to build and run the Web service in debug mode. After 5 or more seconds (depending on your machine, database connection, and so forth), the main Web service page created by the Framework opens in your browser.
Figure 2. The Main Web Service Page. The main Web service page contains general information about a Web service, lists the methods it exposes, and provides a link to its WSDL document. WSDL is an XML document that describes the Web service's public interface. Examining the WSDL document enables you to build a client application that can call the Web service and consume the data it returns. It is a kin to the old COM interface ontracts. 2. Click the GetProducts link to access the test page for this Web method.
4 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 3. Test Page for the Web Method. All test pages have an Invoke button. Because this Web method takes one argument, CategoryID, the Framework also adds a Textbox to enter a value before invoking the method. 3. Click Invoke without entering a CategoryID. A second browser window opens and displays the XML representation of the DataSet returned by this Web method. The actual data is preceded by the schema representation of the DataSet:
- <xs:schema id="NewDataSet" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata=" urn:schemas-microsoft-com:xml-msdata">
- <xs:element name="NewDataSet" msdata:IsDataSet="true"> - <xs:complexType> - <xs:choice maxOccurs="unbounded"> - <xs:element name="Table"> - <xs:complexType> - <xs:sequence> <xs:element name="ProductID" type="xs:int" minOccurs="0" /> <xs:element name="ProductName" type="xs:string" minOccurs="0" /> <xs:element name="SupplierID" type="xs:int" minOccurs="0" /> <xs:element name="CategoryID" type="xs:int" minOccurs="0" />
5 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
<xs:element name="QuantityPerUnit" type="xs:string" minOccurs="0" /> <xs:element name="UnitPrice" type="xs:decimal" minOccurs="0" /> <xs:element name="UnitsInStock" type="xs:short" minOccurs="0" /> <xs:element name="UnitsOnOrder" type="xs:short" minOccurs="0" /> <xs:element name="ReorderLevel" type="xs:short" minOccurs="0" /> <xs:element name="Discontinued" type="xs:boolean" minOccurs="0" /> </xs:sequence> </xs:complexType> </xs:element> </xs:choice> </xs:complexType> </xs:element> </xs:schema> This code shows data for a single product:
- <NewDataSet xmlns=""> - <Table diffgr:id="Table1" msdata:rowOrder="0"> <ProductID>1</ProductID> <ProductName>Chai</ProductName> <SupplierID>1</SupplierID> <CategoryID>1</CategoryID> <QuantityPerUnit>10 boxes x 20 bags</QuantityPerUnit> <UnitPrice>18</UnitPrice> <UnitsInStock>39</UnitsInStock> <UnitsOnOrder>0</UnitsOnOrder> <ReorderLevel>10</ReorderLevel> <Discontinued>false</Discontinued> </Table>
4. Close the browser containing the XML data. 5. In the strCategoryID field type "2" and click Invoke. 6. Scroll through the results, verifying that only those products with CategoryID = 2 are displayed. 7. Close both browser windows.
Creating an ASP .NET Web Application to Consume the Web Service
6 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
You have built the Web service and are now ready to build a client application to consume it. Follow these steps to add an ASP .NET Web Application to your existing Solution. 1. In the Solution Explorer, right-click Solution 'intel_wsNWProducts', point to Add, and then click New Project. 2. Select Visual Basic Projects in the Project Types pane. 3. Select ASP.NET Web Application in the Templates pane. 4. In the Location field type "http:// localhost/intel_wsNWProductsClient". 5. Click OK. The Intel_wsNWProductsClient project is added to the Solution.
Adding Controls to a Web Form
Now you can build a Web Form containing a Textbox and Button that will allow the user to enter a CategoryID and invoke the Web service by clicking the Button. 1. You should see a blank design surface for WebForm1.aspx. (If you are not in Design View, click the Design tab below the Code Editor window.) 2. Right-click the design surface and select Properties. In the Page Layout drop-list select FlowLayout and click OK. FlowLayout is easier to use for designing and positioning form controls than the default GridLayout. 3. Click the design surface and type "CategoryID:". 4. Press CTRL + ALT + T to open the Toolbox. From the Web Forms group select and drag a Textbox to the design surface, placing it to the right of the text you just typed. 5. Press F4 to access the Textbox properties. In the Properties window, change the Columns property to 1. 6. From the Toolbox, select and drag a Button to the design surface, placing it to the right of the Textbox. 7. Press F4 to access the Button properties. In the Properties window, change the Text property to "Get Products". 8. Press Enter to move the cursor to the next line on the design surface. 9. From the Toolbox, select and drag a DataGrid to the design surface. 10. Press F4 to access the DataGrid properties. In the Properties window, below all of the properties click the Auto Format link. Select any Scheme you like and click OK.
7 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 4. Setting Auto Format Schemes.
Adding a Web Reference
If you have experience building applications, you are undoubtedly familiar with the concept of a reference. A reference registers a binary with the development environment so that its members can be accessed programmatically. In fact, when Visual Studio .NET created both the Web service and Web application projects, it automatically included references to the most common .NET assemblies for building each type of project. You can see a list of these assemblies by expanding References in the Solution Explorer. The concept of a Web reference is very similar. The difference is, of course, that the binary you are referencing is remote. It could be thousands of miles away on another server, hosted by a company with which you have no association. As you will see, a Web reference is merely a pointer to the Web service's WSDL document. As mentioned earlier, the WSDL document describes the Web service's public interface. The .NET Framework processes this document and generates a proxy class, which becomes like the other binaries that are locally referenced in your project. It "stands in the place of" the Web service class, allowing you to use its API as if the Web service were local instead of remote. 1. In the Solution Explorer, right-click References under Intel_wsNWProductsClient and select Add Web Reference. 2. In the Address field type "http://localhost/intel_wsNWProducts/Products.asmx". This is the URL to the main Web service page you saw earlier containing information about your Web service and a link to test the Web method. 3. Press Enter. The page appears in the left pane.
8 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 6. Adding a Web Reference. 4. Click Add Reference. Visual Studio .NET will now access the Web service's WSDL document over HTTP and generate a proxy class for you. Notice that a Web References node appears in the Solution Explorer, with a child localhost node. 5. It is worthwhile to examine briefly what is contained in the proxy class. In the Solution Explorer, click the View All Files icon. 6. Expand Web References | localhost | Reference.map. 7. Right-click Reference.vb and select View Code. Examine the proxy class code. Although it is beyond the scope of this article to discuss the code in detail, consider the following noteworthy points. The proxy class derives from System.Web.Services.Protocols.SoapHttpClientProtocol. This class takes care of the low-level Web service connectivity, SOAP messaging and deserialization. Much of its functionality is inherited from other classes in the same namespace. The inherited Url property maintains a reference to the Web service address. Proxy methods have been created for both the synchronous and asynchronous calling of the Web service's methods. When the XML is received back from the Web service, the proxy class takes care of deserializing it—reconstructing the DataSet object from the XML based on the schema information included in the XML stream. 8. Close Reference.vb.
Adding Code to Call the Web Method
With the Web Form controls in place, you are ready to add the code needed to invoke the Web method and display the results in the DataGrid. 1. On the design surface for WebForm1.aspx, double-click the Button to create a Click event handler. 2. In the event handler, add the following code, which creates an instance of the Web service proxy class and calls the GetProducts proxy method:
9 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Dim ws As New localhost.ProductsService() DataGrid1.DataSource = ws.GetProducts(TextBox1.Text) DataGrid1.DataBind()
This is a surprisingly small amount of code, thanks entirely to the proxy class created for you. All of the complex issues involved with connecting to a Web service, creating and receiving SOAP-formatted messages, and deserializing XML are taken care of for you behind the scenes.
Running the Client Application
Running the Web application client from within Visual Studio .NET requires that you first set the startup project and start page. 1. In the Solution Explorer, right-click the intel_wsNWProductsClient project and select Set as Startup Project. 2. Right-click WebForm1.aspx and select Set As Start Page. 3. Press F5 to build and run the Solution in debug mode. 4. When the page appears in the browser, click Get Products. After a brief delay due to the Web service being "just in time" (JIT) compiled by the .NET runtime (this happens only the first time the Web service is invoked), the DataGrid displays with information about all of the Products. 5. In the Textbox type "2" and click Get Products. The DataGrid shows only those Products in the second category.
10 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
Figure 7. The DataGrid. 6. Close the browser.
Conclusion and Resources
Entire books have been written on Web services. Yet with this brief hands-on introduction, you should now have a basic understanding of the following: What a Web service is. Why it solves many of the key problems common to previous distributed programming technologies. How to build a Web service using Visual Studio .NET. How to build a client ASP .NET Web application to consume it. You're ahead of the game! Resources The following Web-based resources will be help you learn more about this incredible new technology that is changing the face of the Internet forever. Microsoft Developer Network (MSDN) Main Web Services Page* "XML Web Service Basics"* "Using Web Services Instead of DCOM"* "Visual Studio .NET: Build Web Applications Faster and Easier Using Web Services and XML"*
11 of 12
11/7/05 20:28
Intel® Software Network - Build and Consume an ASP.NET Web S...
http://www.intel.com/cd/ids/developer/asmo-na/eng/20068.htm?prn=Y
"Creating a .NET Web Service"*
About the Author
Patrick Barnes is a freelance Web application developer, author and consultant located in Cedar Rapids, Iowa. He specializes in n-tier development using ASP .NET, Visual Basic* .NET, SQL Server*, and XML.
The information, opinions, and recommendations in this column are provided by the Author, Patrick Barnes. Intel and its subsidiaries do not necessarily endorse or represent the accuracy of the Author's information, opinions or recommendations, and any reliance upon the Author's statements is solely at your own risk.
12 of 12
11/7/05 20:28
