The basic features of a Stream object include the Read and Write methods that let you read or write bytes. As data is read from or written to a stream, the Stream object maintains a “current position” within the stream that you can adjust using the Seek method, or examine using the Position property. The Length property indicates the size of the readable data. The class also exposes variations of these basic features to allow as much flexibility as possible.

Not every stream supports all features. Some streams are read-only, forward-only constructs that don’t support writing or seeking. Other streams support all possible features. The features available to you depend on the type of stream you use. Since Stream itself is abstract, you must create an instance of one of its derived classes. .NET defines several useful streams ready for your use:

Streams are useful on their own, but you can also combine streams so that an incoming network stream can be immediately encrypted, compressed, and stored in a block of stream memory.

Using a stream is simple; first you create it, and then you start reading and writing bytes left and right. Here’s some sample code I wrote that moves data into and out of a memory stream. It’s loosely based on the code you’ll find in the MSDN documentation for the MemoryStream class.

' ----- The Stream, or There and Back Again.
Dim position As Integer
Dim memStream As IO.MemoryStream
Dim sourceChars(  ) As Byte
Dim destBytes(  ) As Byte
Dim destChars(  ) As Char
Dim asUnicode As New System.Text.UnicodeEncoding(  )

' ----- Create a memory stream with room for 100 bytes.
memStream = New IO.MemoryStream(100)

' ----- Convert the text data to a byte array.
sourceChars = asUnicode.GetBytes( _
   "This is a test of the emergency programming system.")

Try
   ' ----- Store the byte-converted data in the stream.
   memStream.Write(sourceChars, 0, sourceChars.Length)
   ' ----- The position is at the end of the written data.
   '       To read it back, we must move the pointer to
   '       the start again.
   memStream.Seek(0, IO.SeekOrigin.Begin)

   ' ----- Read a chunk of the text/bytes at once.
   destBytes = New Byte(CInt(memStream.Length)) {}
   position = memStream.Read(destBytes, 0, 25)

   ' ----- Get the remaining data one byte at a time,
   '       just for fun.
   While (position < memStream.Length)
      destBytes(position) = CByte(memStream.ReadByte(  ))
      position += 1
   End While

   ' ----- Convert the byte array back to a set of characters.
   destChars = New Char(asUnicode.GetCharCount( _
      destBytes, 0, position)) {}
   asUnicode.GetDecoder(  ).GetChars(destBytes, 0, _
      position, destChars, 0)

   ' ----- Prove that the text is back.
   MsgBox(destChars)
Finally
   memStream.Close(  )
End Try

The comments hopefully make the code clear. After creating a memory stream, I push a block of text into it, and then read it back out. (The text stays in the stream; reading it did not remove it.) Actually, the stream code is pretty simple. Most of the code deals with conversions between bytes and characters. If it looks overly involved, that’s because it is.

For me, all that converting between bytes and characters is for the birds. When I write business applications, I typically deal in dates, numbers, and strings: customer names, order dates, payment amounts, and so on. I rarely have a need to work at the byte level. I sure wish there was a way to send this byte stuff down a programming stream of its own so that I wouldn’t have to see it anymore.

Lucky me! .NET makes some wishes come true. Although you can manipulate streams directly if you really want to or need to, the System.IO namespace also includes several classes that provide a more programmer-friendly buffer between you and the stream. These classes—implemented as distinct readers and writers of stream data—provide simplified methods of storing specific data types, and retrieving them back again.

The readers and writers are designed for single-direction start-to-finish processing of data. After creating or accessing a stream, you wrap that stream with either a reader or a writer, and begin traversing the extent of the stream from the beginning. You always have access to the underlying stream if you need more fine-tuned control at any point.

There are three main pairs of readers and writers:

One additional pair—TextReader and TextWriter—provides the base class for the other nonbinary readers and writers. You can’t create instances of them directly, but they do let you treat the stream and string versions of the readers and writers generically.

With these new tools, it’s easier to process non-Byte data through streams. Here’s a rewrite of the simple memory stream code I wrote earlier, adjusted to use a StreamReader and StreamWriter:

' ----- The Stream, or There and Back Again.
Dim memStream As IO.MemoryStream
Dim forWriting As IO.StreamWriter
Dim forReading As IO.StreamReader
Dim finalMessage As String
Dim asUnicode As New System.Text.UnicodeEncoding(  )

' ----- Create a memory stream with room for 100 bytes.
memStream = New IO.MemoryStream(100)
Try
   ' ----- Wrap the stream with a writer.
   forWriting = New IO.StreamWriter(memStream, asUnicode)

   ' ----- Store the original data in the stream.
   forWriting.WriteLine( _
      "This is a test of the emergency programming system.")
   forWriting.Flush(  )

   ' ----- The position is at the end of the written data.
   '       To read it back, we must move the pointer to
   '       the start again.
   memStream.Seek(0, IO.SeekOrigin.Begin)

   ' ----- Create a reader to get the data back again.
   forReading = New IO.StreamReader(memStream, asUnicode)

   ' ----- Get the original string.
   finalMessage = forReading.ReadToEnd(  )

   ' ----- Prove that the text is back.
   MsgBox(finalMessage)
Finally
   memStream.Close(  )
End Try

That code sure is a lot nicer without all of that conversion code cluttering up the works. (We could simplify it even more by leaving out all of the optional Unicode encoding stuff.) Of course, everything is still being converted to bytes under the surface; the memory stream only knows about bytes. But StreamWriter and StreamReader take that burden away from us, performing all of the messy conversions on our behalf.

Most Stream processing involves files, so let’s use a StreamReader to process a text file. Although we already decided in Chapter 14 that INI files are a thing of the past, it might be fun to write a routine that extracts a value from a legacy INI file. Consider a file containing this text:

[Section0]
Key1=abc
Key2=def

[Section1]
Key1=ghi
Key2=jkl

[Section2]
Key1=mno
Key2=pqr

Now there’s something you don’t see everyday, and with good reason! Still, if we wanted to get the value for Key2 in section Section1 (the “jkl” value), we would have to fall back on the GetPrivateProfileString API call from those bad old pre-.NET programming days. Or, we could implement a StreamReader in a custom function all our own.

Public Function GetINIValue(ByVal sectionName As String, _
      ByVal keyName As String, ByVal iniFile As String) _
      As String
   ' ----- Given a section and key name for an INI file,
   '       return the matching value entry.
   Dim readINI As IO.StreamReader
   Dim oneLine As String
   Dim compare As String
   Dim found As Boolean

   On Error GoTo ErrorHandler

   ' ----- Open the file.
   If (My.Computer.FileSystem.FileExists(iniFile) = False) _
      Then Return ""
   readINI = New IO.StreamReader(iniFile)

   ' ----- Look for the matching section.
   found = False
   compare = "[" & Trim(UCase(sectionName)) & "]"
   Do While (readINI.EndOfStream = False)
      oneLine = readINI.ReadLine(  )
      If (Trim(UCase(oneLine)) = compare) Then
         ' ----- Found the matching section.
         found = True
         Exit Do
      End If
   Loop

   ' ----- Exit early if the section name was not found.
   If (found = False) Then
      readINI.Close(  )
      Return ""
   End If

   ' ----- Look for the matching key.
   compare = Trim(UCase(keyName))
   Do While (readINI.EndOfStream = False)
      ' ----- If we reach another section, then the
      '       key wasn't there.
      oneLine = Trim(readINI.ReadLine(  ))
      If (Len(oneLine) = 0) Then Continue Do
      If (oneLine.Substring(0, 1) = "[") Then Exit Do

      ' ----- Ignore lines without an "=" sign.
      If (InStr(oneLine, "=") = 0) Then Continue Do
     ' ----- See if we found the key. By the way, I'm
      '       using Substring(  ) instead of Left(  ) so
      '       I don't have to worry about conflicts with
      '       Form.Left in case I drop this routine into
      '       a Form class.
      If (Trim(UCase(oneLine.Substring(0, _
            InStr(oneLine, "=") − 1))) = compare) Then
         ' ----- Found the matching key.
         readINI.Close(  )
         Return Trim(Mid(oneLine, InStr(oneLine, "=") + 1))
      End If
   Loop

   ' ----- If we got this far, then the key was missing.
   readINI.Close(  )
   Return ""

ErrorHandler:
   ' ----- Return an empty string on any error.
   On Error Resume Next
   If (readINI IsNot Nothing) Then readINI.Close(  )
   readINI = Nothing
   Return ""
End Function

This routine isn’t an exact replacement for GetPrivateProfileString; it doesn’t support a default return value, or perform file caching for speed. You could improve the routine with better error handling. But it does retrieve the value we seek, and it does it by reading the INI file one line at a time through a StreamReader.

MsgBox(GetINIValue("Section1", "Key2", iniFilePath))
   ' ----- Displays 'jkl'

Most of the My.Computer.FileSystem object’s members exist to replace or supplement file management features already present in Visual Basic. Table 15-2 lists some of the long-standing file and directory interaction features in Visual Basic, and their equivalents in My.Computer.FileSystem.

Why would Microsoft introduce so many new My features that duplicate existing Visual Basic features? Perhaps it’s a way to bring consistency to file-based programming practices through a more object-oriented approach. Or maybe it’s yet another move by Microsoft, the U.S. government, the Knights Templar, Burger King, and other groups set on world domination by controlling you, your family, and your community through the “hidden hand” of extra-long source code statements.

The My.Computer.FileSystem.OpenTextFileReader and parallel OpenTextFileWriter methods provide shortcuts to the filename-based constructor for StreamReader and StreamWriter objects. The statement:

Dim inputStream As IO.StreamReader = _
   My.Computer.FileSystem.OpenTextFileReader( _
   fileNamePath)

is identical to:

Dim inputStream As New IO.StreamReader(fileNamePath)

For me, the second version is better due to its terse nature, but it’s between you and your source code review team as to which one you will use.

If you want to load the entire contents of a file into either a String or a Byte array, there’s no need to open up a stream now that My includes the My.Computer.FileSystem.ReadAllText and related ReadAllBytes methods. This statement dumps the entire contents of a file into a String:

Dim wholeFile As String = _
   My.Computer.FileSystem.ReadAllText( _
   fileNamePath)

The My.Computer.FileSystem.WriteAllText and WriteAllBytes methods do the same thing, but in the opposite direction. There’s an append Boolean argument that lets you either append or replace the new content relative to any existing content in the file.

My.Computer.FileSystem.WriteAllText( _
   fileNamePath, dataToWrite, True)  ' True=append

One feature that has always been missing from Visual Basic is the ability to conveniently scan a delimited file (such as tab-delimited or comma-delimited) or a fixed-width-field file, and extract the fields on each line without a lot of extra parsing code. Visual Basic now includes the Microsoft.VisualBasic.FileIO.TextFieldParser object that simplifies this process. This object lets you indicate either a field delimiter (such as the tab character) or an array of column sizes. Once you associate it with a file path, it reads each data line, breaking up the distinct fields for you into a string array. The My.Computer.FileSystem.OpenTextFieldParser method opens the file and defines the parsing method in one fell swoop.

Dim dataFields(  ) As String
Dim sourceFile As FileIO.TextFieldParser

' ----- Open the file with tab-delimited fields.
sourceFile = My.Computer.FileSystem.OpenTextFieldParser( _
   sourceFilePath, vbTab)

' ----- Process each line.
Do While Not sourceFile.EndOfData
   dataFields = sourceFile.ReadFields(  )
   ' ----- dataFields is a simple string array,
   '       so you can examine each field directly.
   If (dataFields(0) = "NEW") Then
   ' ----- and so on...
Loop
sourceFile.Close(  )

The TextFieldParser object can also detect comment lines and ignore them silently. I am sure that it’s using a StreamReader secretly hidden inside the object’s black box. Although the internals are hidden from view, the exposed features of this object make it a snap to process field-based text files.

Whenever an error occurs in the Library application, the GeneralError routine first shows the error message to the user, and then logs it to any configured “log listeners.”

Public Sub GeneralError(ByVal routineName As String, _
      ByVal theError As System.Exception)
   ' ----- Report an error to the user.
   On Error Resume Next

   MsgBox("The following error occurred at location '" & _
      routineName & "':" & vbCrLf & vbCrLf & _
      theError.Message, MsgBoxStyle.OkOnly Or _
      MsgBoxStyle.Exclamation, ProgramTitle)
   My.Application.Log.WriteException(theError)
End Sub

So, who’s listening? If you are running the program within Visual Studio, Visual Basic always configures a log listener that displays the text in the Immediate Window panel. But that doesn’t do much good in a compiled and deployed application.

You can design your own log listeners, but .NET also includes several predefined listeners, all of which can be enabled and configured through the application’s app.config file. If you access the “After” version of Chapter 14’s project, you will find content in its app.config file that sets up one such listener. Here’s a portion of that file, showing just the relevant sections:

<system.diagnostics>
  <sources>
    <!-- This section defines the logging configuration
         for My.Application.Log -->
    <source name="DefaultSource" switchName="DefaultSwitch">
      <listeners>
        <add name="FileLog"/>
      </listeners>
    </source>
  </sources>

  <switches>
    <add name="DefaultSwitch" value="Information" />
  </switches>

  <sharedListeners>
    <add name="FileLog" type=
    "Microsoft.VisualBasic.Logging.FileLogTraceListener,
    Microsoft.VisualBasic, Version=8.0.0.0, Culture=neutral,
    PublicKeyToken=b03f5f7f11d50a3a,
    processorArchitecture=MSIL"
    initializeData="FileLogWriter"/>
  </sharedListeners>
</system.diagnostics>

The <sharedListeners> section defines the details for a particular log listener. In this case, it’s the FileLogTraceListener listener, a class in the Microsoft.VisualBasic.Logging namespace. It’s enabled in the <source>/<listeners> section, where it’s included through an <add> tag. There’s a lot of stuff here that seems bizarre or extremely picky (such as the public key token). Fortunately, it’s all documented in MSDN if you ever need the details.

The FileLogTraceListener listener sends relevant logging data to an application-specific logfile. By default in Windows Vista, the file resides in the following:

C:UsersusernameApplication Data
CompanyProductVersionAppName.log

The username part is replaced by the name of the currently logged-in user. The Company, Product, and Version parts represent the company name, product name, and version number of your assembly as defined in its assembly attributes. AppName is the name of your application with the .exe extension stripped off. On my Windows Vista system, the logfile for the Library Project appears here:

C:UsersusernameApplication Data
ACMELibrary1.0.0.0Library.log

If you don’t like that location, you can change the output to any location you choose. To do it, you’ll need to alter the <add> tag in the <sharedListeners> section, adding two additional attributes to that tag.

<sharedListeners>
  <add name="FileLog" type=
     "Microsoft.VisualBasic.Logging.FileLogTraceListener,
     Microsoft.VisualBasic, Version=8.0.0.0, Culture=neutral,
     PublicKeyToken=b03f5f7f11d50a3a,
     processorArchitecture=MSIL"
     initializeData="FileLogWriter"
     location="Custom"
customLocation="c:	emp" />
</sharedListeners>

The new location and customLocation attributes do the trick. Set the customLocation attribute to the directory where the logfile should go. These attributes link to properties of the same name in the FileLogTraceListener class. Visual Studio’s documentation describes these properties and attributes, plus others that are available for you to configure through app.config.

This app.config change is based on an MSDN article titled “How to: Write Event Information to a Text File” that you can search for in your online help. (Use the Search feature, not the Index feature.)

Another MSDN article, “Walkthrough: Changing Where My.Application.Log Writes Information,” describes how to send log output to more than just a simple text file. It discusses ways to log application information to the system Event Log, to a delimited file, to an XML-formatted file, and to the console display.

Some of the changes you need to make to the app.config file are, again, mysterious, so I’ll just list them here for your examination. Add the following content to the app.config file to define the available listeners:

<add name="EventLog"
  type="System.Diagnostics.EventLogTraceListener,
     System, Version=2.0.0.0,
     Culture=neutral, PublicKeyToken=b77a5c561934e089"
     initializeData="sample application"/>

<add name="Delimited"
  type="System.Diagnostics.DelimitedListTraceListener,
  System, Version=2.0.0.0,
  Culture=neutral, PublicKeyToken=b77a5c561934e089"
  initializeData="c:	empSomeFile.txt"
  delimiter=";;;"
  traceOutputOptions="DateTime" />

<add name="XmlWriter"
  type="System.Diagnostics.XmlWriterTraceListener,
  System, Version=2.0.0.0,
  Culture=neutral, PublicKeyToken=b77a5c561934e089"
  initializeData="c:	empSomeFile.xml" />
<add name="Console"
  type="System.Diagnostics.ConsoleTraceListener,
  System, Version=2.0.0.0,
  Culture=neutral, PublicKeyToken=b77a5c561934e089"
  initializeData="true" />

The initializeData attribute in each entry contains the values sent to the arguments of the relevant class constructor. Other attributes (except for type) modify the properties of the same name in the class specified through the type attribute. For all the options available to you for each listener, look up its class entry in the Visual Studio documentation.

To enable any of these listeners, use an <add> tag in the <source>/<listeners> section. The following XML block enables all the listeners defined in this chapter’s project:

<sources>
  <!-- This section defines the logging configuration
       for My.Application.Log -->
  <source name="DefaultSource" switchName="DefaultSwitch">
    <listeners>
      <add name="FileLog"/>
      <add name="EventLog" />
      <add name="Delimited" />
      <add name="XmlWriter" />
      <add name="Console" />
    </listeners>
  </source>
</sources>

Since we have a little time left, let’s talk about obtaining a bar code font. The Library Project will include bar code printing support, but only if you have a bar code font installed on your system. It’s no emergency, but you should obtain one before you reach Chapter 18, where we develop the bar code configuration code.

When you downloaded the code for this book, it didn’t include a bar code font. It’s all due to licensing issues and the like, you understand. But bar code fonts are easy to get. You can purchase a professional bar code font if you want to, and if you plan to deploy this project into an actual library setting, you probably should. But if you’re only reading this book for the great humor, you can download one of the many free bar code fonts available on the Internet. I’ve included some links to bar code font providers on the web site where you obtained the source code for this book. Even if you don’t plan to use the bar code printing features, I recommend that you download a free bar code font just so that you can try out some of the Chapter 18 features.

Once you’ve installed the font, you will need to tell the Library program to use it. The settings form we designed in the previous chapter included a selection field for this font. It’s the Barcode Font Name field on the System-Wide tab of the Maintenance form. You can see it in the middle of Figure 14-6. I made it a system-wide setting because it seemed best to have all administrators in a single library using a common font.

If your font is a “Code 3 of 9” bar code font (also called “Code 39”), make sure you select the Barcode is “Code 39” or “Code 3 of 9” field on that same form. (The provider of the font will let you know whether it is a Code 3 of 9 font or not.) These fonts require an asterisk before and after the bar code number. Selecting this field will cause the Library program to add the asterisk characters automatically.

Well, I’m getting tired of talking about files, be they fonts or config files. In the next chapter, we’ll go back into the world of code and its fraternal twin, data.