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 needsDispose
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 theADO.NET
-related classes. Here is a handy blog post that provides a list of of the most common .NET objects that requireDispose.
If all else fails, look at the class's documentation. For example, here the documentation for theStreamWriter
class that shows that it has aDispose
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? TheDataSet
has for many years caused endless arguments about its need forDispose.
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 theiDisposable
interface. Don't try to use it with AVR objects like disk files or DataGate DB connections that need aClose
orDisconnect
method. Continue to close those objects with theirClose
orDisconnect
methods as you have been.