Chapter 11: Integrating Binary Data into .NET Web Services

Throughout this book, you have used web services to return a wide range of data. In Chapter 2, “Creating Your First Web Services,” you created web services that return various data types, including structures and arrays. In this chapter, you will learn how to return large amounts of binary data, such as an image file, audio file, or video file. Using the techniques this chapter presents, you can use web services to provide access to a wide range of data, such as a Microsoft Word or Excel file.

To begin, you will create programs that download binary data from a web service and then store the data into a file on your disk. After that, you will download and use the binary data. Meaning, you will create programs that download and display image files and that download and play back audio and video files.

Understanding the Process of Working with Binary Data

As you will learn, to download binary data, a web service will store the data within a byte array. In Chapter 2, you learned that a web service method can return an array of values to the client. Behind the scenes, to improve performance and to support the binary-data transfer, the SOAP protocol will encode the data using Base64 encoding. When the client program receives the data, the SOAP protocol will decode the Base64 data, creating a byte array the client can use to access the binary data.

The Visual Basic .NET program in Listing 11.1, BinaryData.vb, illustrates how a web service method creates a byte array to store the contents of a file. When you run the program, your screen will display a form, similar to that shown in Figure 11.1, that lets you specify target and destination filenames. After you specify the filenames and click the Copy File button, the program will copy the source file’s contents to the target file.

Figure 11.1: Using a byte array to copy a file’s contents

To create the BinaryData.vb program, perform these steps:

1. Within Visual Studio .NET, select the File menu New Project option. Visual Studio .NET will display the New Project dialog box.

2. Within the New Project dialog box Project Types list, click Visual Basic Projects. Then, within the Templates field, click Windows Application. Finally, within the Location and Name fields, specify the folder within which you want to store the program and the program name BinaryData. Select OK. Visual Studio .NET will display a page onto which you can drag and drop the program’s controls.

3. Using the Toolbox, drag and drop the button and text boxes previously shown in Figure 11.1 onto the page.

4. Select the View menu Code option. Visual Studio .NET will display the program’s source code. Within the source code add the program statements in Listing 11.1.

Listing 11.1 BinaryData.vb

Imports System.IO Public Class Form1     Inherits System.Windows.Forms.Form #Region " Windows Form Designer generated code "   ' Code not shown #End Region Private Sub CopyFile(ByVal Source As String, ByVal Target As String)   Dim InputFile As FileStream   Dim OutputFile As FileStream   Dim FileLength As Long   Try     InputFile = File.Open(Source, FileMode.Open, FileAccess.Read)     OutputFile = File.Open(Target, FileMode.Create, FileAccess.Write)     FileLength = InputFile.Length     Dim DataBuffer(FileLength - 1) As Byte     InputFile.Read(DataBuffer, 0, FileLength)     OutputFile.Write(DataBuffer, 0, FileLength)     InputFile.Close()     OutputFile.Close()     TextBox3.Text = "File copy complete"   Catch Ex As Exception     TextBox3.Text = Ex.Message   End Try End Sub Private Sub Button1_Click(ByVal sender As System.Object, _ ÄByVal e As System.EventArgs) Handles Button1.Click   Try     If (TextBox1.Text.Length > 0) Then       If (TextBox2.Text.Length > 0) Then         CopyFile(TextBox1.Text, TextBox2.Text)       Else         TextBox3.Text = "Must specify target file"       End If     Else       TextBox3.Text = "Must specify source file"     End If   Catch Ex As Exception     TextBox3.Text = Ex.Message   End Try End Sub End Class

The program’s processing is similar to that which web services and client programs perform to exchange binary data. To begin, the web service will read a file’s contents into a byte array:

InputFile = File.Open(Source, FileMode.Open, FileAccess.Read) FileLength = InputFile.Length Dim DataBuffer(FileLength - 1) As Byte InputFile.Read(DataBuffer, 0, FileLength) InputFile.Close()

The client program, in turn, must convert the binary data it receives back into a file. The following code snippet illustrates how the client can write the array’s contents to a file:

OutputFile = File.Open(Target, FileMode.Create, FileAccess.Write) FileLength = DataBuffer.Length OutputFile.Write(DataBuffer, 0, FileLength) OutputFile.Close()

Exchanging binary data files with a web service is simply a matter of receiving a byte array and then storing that data within a file.