An often-overlooked feature of ASNA Visual RPG (AVR) is its BegUsing operation. This operation was added a couple of versions ago and allows for a more streamlined use of objects that provide a Dispose method—that must be called before the object instance goes out of scope.

The Dispose method is added to an object when it implements the iDisposable interface. This interface provides the Dispose mechanism for releasing unmanaged resources. While you may need to implement this interface in objects you create, it's not likely. iDisposable is only necessary when the object uses unmanaged COM resources. While custom objects needing iDisposable are rare, many .NET intrinsic objects implement this interface. For example, .NET's StreamWriter and its new ZipArchive object (that lets you programmatically zip and unzip files with .NET), both provide a Dispose method that must be called before the object instance goes out of scope.

Not calling Dispose on objects that need it can lead to out-of-memory and other unpredictable errors. Calling Dispose also almost requires a Try/Finally, which makes it doubly annoying to need to call Dispose.

How do you know if an object has a Dispose method that you must call before it goes out of scope? Most of the time, when an object needs Dispose method, it is an object that uses a low-level Windows operating system facility: reading and writing text files, working with memory streams, and many of the ADO.NET-related classes. Here is a handy blog post that provides a list of of the most common .NET objects that require Dispose. If all else fails, look at the class's documentation. For example, here the documentation for the StreamWriter class that shows that it has a Dispose method.

Beware, though, there are a few exceptions to the rule. There is the occasional .NET object that has a vestigial Dispose method that doesn't really need to be called. Crazy, huh? The DataSet has for many years caused endless arguments about its need for Dispose. If you can't sleep some night, read about that here.

AVR's BegUsing operation

Before AVR got BegUsing, this is how you would have used the StreamWriter object to effectively dispose it:

DclFld writer Type(System.IO.StreamWriter)         

Try
    writer =  File.CreateText("c:\users\roger\newfile1.txt")
    writer.WriteLine("Neil")
    writer.WriteLine("Young")
Finally 
    If writer <> *Nothing
        w.Dispose() 
    EndIF 
EndTry 

 

BegUsing streamlines the code needed to perform the Dispose and the Try/Catch to this code:

BegUsing writer Type(StreamWriter) Value(File.CreateText("c:\users\roger\newfile2.txt"))
    writer.WriteLine("Neil")
    writer.WriteLine("Young")          
EndUsing

 

You won't need BegUsing often, but when you do it's quite handy. Also, its presence makes it easier to translate C# examples to AVR.

BegUsing is intended only for objects that implement the iDisposable interface. Don't try to use it with AVR objects like disk files or DataGate DB connections that need a Close or Disconnect method. Continue to close those objects with their Close or Disconnect methods as you have been.