E:\web\learnaspcom\htdocs\freebook\learn\ubtoc.xml LearnAsp.com - ASP ASP.net Free Lessons
Search Search

#1 worldwide
FREE Coding Lessons
since 1996
   THE BEST WAY to learn ASP & Asp.net!
Advertise Here!
click for details 		Credits Host:
DiscountASP.net 		Server Admin:
The "Team" 		Contact Info.
Charles M. Carroll 		<Asp.net blog>
<personal site>
xxx

Utility Belt: Documentation, Goals
by Charles Carroll

The goals of the Utility Belt library are

  • being completely easy for beginner

  • taking common tasks that require 10 to 50 lines of code in the framework and reducing them to 1 lines.

  • Error trapping that is professional quality for beyond what a novice normally codes transparently

  • Scalable, stress-tested and Unit testing of code.

  • DB functions are not separate for SQLserver or OLEDB. They will pick the appropriate library for efficient execution under the covers transparently. If they use OLEDB on a data source that has a faster managed provider available they will issue appropriate warnings to get better provider.

  • Caching of HTTP Fetches and Database caching at the SQL Query level is easy to implement for dozens to hundreds of lines of code with a simple one line of code or simple utilitybelt.config key config file changes.

The devil is in the details:

  • Easy to remember names for functions and subs. The SUBs and functions have a design goal of reducing dozens of lines of code down to 1 line and each Sub and function has dozens of easy variations so it can be used many common sense ways.

  • Most functions are not coupled in a way that they must be called in any particular order or are interdependent. It is not structured like some API where to call one method or function some kind of other methods or function must be called first.

  • Error trapping is robust and runtime errors are formatted nicely on the web page, and if desired emailed to the relevant person(s) (and also logged in EventLogs and/or XML and/or SQLserver tables and/or a UserDefined mechanism) so a runtime error that occurred can be audited and tracked. In addition to superb error trapping it generates Advice to suggest how to tweak your code, Warnings for potential problems in your code that may be serious or may not.

  • Memory and Resource leaks are avoided by meticulous coding and testing. So your servers are never adversely affected by runtime errors that less careful code that does not dispose of resources properly.

The Commands and Functions are presented below. The sample programs generally exercise all these commands.

Tip for Newbies: DbPopulate, DbExec,SQLGenerateInsert,SQLGenerateUpdate and Xray are the best starter commands. Also the Options Debug-on and Xray-To-Page-On are essential to master quickly. DbPopulate is 1 line of code that encapsulates the code to databind and error trap webcontrols with 1 line of code or the code to achieve an ExecuteScalar or the code to return arrays/datareaders.

SUBs and Functions Listing

Array_1dRandomize(array,int) - Re-arranges  array order randomly making n passes through the array as specified in second parameter. 1 pass is sufficient to sort it but more passes are fine although they eat up CPU time.

DBExec(strConn, strSQL) - the equivalent of ADO.net executeNonquery. sample @
http://www.learnasp.com/freebook/learn/ub_dbexec_sqlgenerateinsert_sqlclient.aspx

DBPopulate - see ../freebook/learn/utilitybelt_docs_dbpopulate.aspx for docs and samples

Dispose() - In a web page almost always called in Page_PreRender(...) event. Must be called to ensure that error and all diagnostic/advice messages appear on a page. Guarantees that all logs are created and/or flushed, and if many UB calls generated many errors they are not presented 1 at a time, instead all are reported once dispose is called. All the samples utilize this method.

SUB Page_PreRender(s as object, e as eventargs)
    ub1.Dispose()
END SUB

FileMapIfNeeded(strFilename,strDesc) - Given a filename it can apply server.mappath if needed. Reports a Hint with the supplied description if the filename does not exist to simplify error trapping.

FileRead(strFileName,array) - Transfers an ASCII file to an array.
http://www.learnasp.com/freebook/learn/utilitybelt_fileread_array.aspx

FileRead(strFileName,string) - Transfers an ASCII file to a string. Will benefits from file-caching in 1.0 - not implemented yet.
http://www.learnasp.com/freebook/learn/utilitybelt_fileread_string.aspx

FileWrite(strFileName,array) - Places an ASCII file on disk where each line in array is sent to 1 line in the file.
http://www.learnasp.com/freebook/learn/utilitybelt_filewrite_array.aspx

FileWrite(strFileName,string) - Places an ASCII file on disk.
http://www.learnasp.com/freebook/learn/utilitybelt_filewrite_string.aspx

Options(strOptions) - sends a command or several commands to Utility Belt to alter its behavior. It will issue warnings to developers and LOG entries if it is passed unknown options but Utility Belt will not halt or throw an error if it encounters an unknown option


see full documentation @ ../freebook/learn/utilitybelt_docs_options.aspx for full documentation.

HTTPGrab(strURL) - fetches a string when supplied a website address, i.e. "http://www.cnn.com". All requests it process can be cached by standard UtilityBelt methods.
samples @
http://www.learnasp.com/freebook/learn/utilitybelt_httpgrab.aspx

HttpPost(hashtable) - Posts a request to a HTTP server.
samples @
http://www.learnasp.comlfreebook/learn/utilitybelt_httppost.aspx

Log(strDesc, strValue)- Replacement for trace.write. Several advantage including that it respects XrayOn, XrayOff option commands. Like an Xray it can be diverted/displayed on a webpage or log instead of, in addition to, the trace stream.

LogException(strDescription,exception) - If you want to get all the benefits of UB error trapping in your own code (formatted error messages, emails sent when runtime errors occur, etc.). You would use this for example:

TRY
    ... your code here ...
CATCH exc as exception
    LogException("My Description of Bad stuff",exc)
END TRY

MailMsg(hashtable) - Emails a message. See sample program for parameter usage. Current version uses Smtpmail.send.
(1.0 can also do high speed sends by writing the files directly to mail queue).
Samples @
http://www.learnasp.com/freebook/learn/utilitybelt_mailsend.aspx

MailMsgTest(strFrom,strTo) - function that attempts to email a test message to a specified email address. Returns true if the email was sent by UtilityBelt without error.
Samples @
http://www.learnasp.com/freebook/learn/utilitybelt_mailsend.aspx

NullTest(object) - returns true/false if the object tested matches the objNull property.

(next version) PageWalk(Delegate) - Walks every control on a page and then invokes a delegate for each control so that the controls can be examined/manipulated by the delegate.

Release(Object) - Does the correct garbage collection for any object. FileStreams, Connection objects, dataReaders, etc. You send it an object and this thing gracefully releases it/disposes it.

function ScriptcolorCode(strFileName) - given an .aspx or VB.net or C# file returns a nicely formated HTML string with color coding. Useful for anyone who wants to display source code (tutorial sites or the like).
  Sample @
http://www.learnasp.com/freebook/learn/utilitybelt_scriptcolorcode.aspx

spDBPopulate - see ../freebook/learn/utilitybelt_docs_dbpopulate.aspx for docs and samples

SQLGenerateUpdate(strConnect,hashtable) - returns a SQL update statement generated from contents of hashtable.
Hashtable elements are "table_name"' "table_primarykey", "table_primarykey_value" and each field name and value can be used as hash table key and value respectively.
   Sample @
 http://www.learnasp.com/freebook/learn/utilitybelt_sqlgenerateupdate.aspx

SQLGenerateInsert(strConnect,hashtable) - returns a SQL Insert Into statement generated from contents of hashtable.
Hashtable elements are "table_name"' and each field name and value can be used as hash table key and value respectively.
    Sample @ http://www.learnasp.com/freebook/learn/utilitybelt_sqlgenerateinsert.aspx

TOC(strFileName,hashtable) - returns a multi-level HTML table of contents  generated from contents of hashtable.
   Sample @ http://www.learnasp.com/freebook/learn/utilitybelt_toc.aspx

TOCBar(strFileName,hashtable) - returns a current/prev/next navigator HTML table of contents  generated from contents of hashtable.
Sample @
http://www.learnasp.com/freebook/learn/utilitybelt_tocbar.aspx

function WebConfigGrab(strKey): - function grabs the value given a web.config key. It will emit a warning if the key does not exist or results in a blank value (to simplify troubleshooting).

wsAmazonAsinSearch(hashtable): - function does an ASIN search against Amazon.com and return XML answer. Hashtable key "type" can be "lite" or "heavy".
Sample Code @
/http://www.learnasp.com/freebook/learn/utilitybelt_amazonasinsearch.aspx

wsAmazonKeywordSearch - not documented yet.

wsAmazonBrowseNodeSearch - not documented yet.

wsAmazonThirdPartySellerSearch - not documented yet.

wsAmazonMarketplaceSearch - not documented yet.

wsAmazonUpcSearch - not documented yet.

wsAmazonExchangeSearch - not documented yet.

wsAmazonAuthorSearch - not documented yet.

wsAmazonArtistSearch - not documented yet.

XMLToDataset(strfilename) - function that returns a dataset by parsing XML File. Version 1.0 benefits from file caching.

Xray(object, str)- This can dump the contents/elements of most complex .net objects (hashtables, datatables, datasets, arrays, etc.) to the trace stream or the page.
Sample Code @
http://www.learnasp.com/freebook/learn/utilitybelt_xray.aspx

OBJECT PROPERTIES (all are optional)

intCacheMinutes

intCacheSeconds

plcException - a placeholder where Exceptions, Hints and Advice will be displayed on the webpage. If not set, defaults to end of page.

plcXray - a placeholder where Xrays are sentif the Xray-To-Page-On is set.  If not set, defaults to end of page.

There are many worthy charities!!. But perhaps help starving children in Africa or South America AND help Charles too. a $5 tip buys him lunch at McDonalds, a $20 tip buys his kid Hitoshi a new computer game, a $39 tip buys his daughter Michiko a few nice outfits. See our donor list.