VB.NET Comment Statements

The supporting VB.NET Miscellaneous Statements are Error, Mid, RaiseEvent,          Randomize,Stop, Yield

Error Statement

Simulates the occurrence of an error.

Syntax

Error errornumber  

Parts

errornumber
Required. Can be any valid error number.

Remarks

The Error statement is supported for backward compatibility. In new code, especially when creating objects, use the Err object's Raise method to generate run-time errors.

If errornumber is defined, the Error statement calls the error handler after the properties of the Err object are assigned the following default values:

Property	Value
Number	Value specified as argument to Error statement. Can be any valid error number.
Source	Name of the current Visual Basic project.
Description	String expression corresponding to the return value of the Error function for the specified Number, if this string exists. If the string does not exist, Description contains a zero-length string ("").
HelpFile	The fully qualified drive, path, and file name of the appropriate Visual Basic Help file.
HelpContext	The appropriate Visual Basic Help file context ID for the error corresponding to the Number property.
LastDLLError	Zero.

If no error handler exists, or if none is enabled, an error message is created and displayed from the Err object properties.

Requirements

Namespace: Microsoft.VisualBasic

Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

See also

• Clear
• Err
• Raise
• On Error Statement
• Resume Statement
• Error Messages

Mid Statement

Replaces a specified number of characters in a String variable with characters from another string.

Syntax

Mid( _  
   ByRef Target As String, _  
   ByVal Start As Integer, _  
   Optional ByVal Length As Integer _  
) = StringExpression  

Parts

Target
Required. Name of the String variable to modify.

Start
Required. Integer expression. Character position in Target where the replacement of text begins. Start uses a one-based index.

Length
Optional. Integer expression. Number of characters to replace. If omitted, all of String is used.

StringExpression
Required. String expression that replaces part of Target.

Exceptions

Exception type	Condition
ArgumentException	Start <= 0 or Length < 0.

Remarks

The number of characters replaced is always less than or equal to the number of characters in Target.

Visual Basic has a Mid function and a Mid statement. These elements both operate on a specified number of characters in a string, but the Mid function returns the characters while the Mid statement replaces the characters. For more information, see Mid.

Requirements

Namespace: Microsoft.VisualBasic

Module: Strings

Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

See also

• Mid
• Strings
• Introduction to Strings in Visual Basic

RaiseEvent Statement

Triggers an event declared at module level within a class, form, or document.

Syntax

RaiseEvent eventname[( argumentlist )]  

Parts

eventname
Required. Name of the event to trigger.

argumentlist
Optional. Comma-delimited list of variables, arrays, or expressions. The argumentlist argument must be enclosed by parentheses. If there are no arguments, the parentheses must be omitted.

Remarks

The required eventname is the name of an event declared within the module. It follows Visual Basic variable naming conventions.

If the event has not been declared within the module in which it is raised, an error occurs. The following code fragment illustrates an event declaration and a procedure in which the event is raised.

' Declare an event at module level.
Event LogonCompleted(ByVal UserName As String)

Sub Logon(ByVal UserName As String)
    ' Raise the event.
    RaiseEvent LogonCompleted(UserName)
End Sub

You cannot use RaiseEvent to raise events that are not explicitly declared in the module. For example, all forms inherit a Click event from System.Windows.Forms.Form, it cannot be raised using RaiseEvent in a derived form. If you declare a Click event in the form module, it shadows the form's own Click event. You can still invoke the form's Click event by calling the OnClick method.

By default, an event defined in Visual Basic raises its event handlers in the order that the connections are established. Because events can have ByRef parameters, a process that connects late may receive parameters that have been changed by an earlier event handler. After the event handlers execute, control is returned to the subroutine that raised the event.

See also

• Events
• Event Statement
• AddHandler Statement
• RemoveHandler Statement
• Handles

Throw Statement

Throws an exception within a procedure.

Syntax

Throw [ expression ]

Part

expression Provides information about the exception to be thrown. Optional when residing in a Catch statement, otherwise required.

Remarks

The Throw statement throws an exception that you can handle with structured exception-handling code (Try...Catch...Finally) or unstructured exception-handling code (On Error GoTo). You can use the Throw statement to trap errors within your code because Visual Basic moves up the call stack until it finds the appropriate exception-handling code.

A Throw statement with no expression can only be used in a Catch statement, in which case the statement rethrows the exception currently being handled by the Catch statement.

The Throw statement resets the call stack for the expression exception. If expression is not provided, the call stack is left unchanged. You can access the call stack for the exception through the StackTrace property.

See also

• Try...Catch...Finally Statement
• On Error Statement

Yield Statement

Sends the next element of a collection to a For Each...Next statement.

Syntax

Yield expression  

Parameters

Term	Definition
expression	Required. An expression that is implicitly convertible to the type of the iterator function or Get accessor that contains the Yield statement.

Remarks

The Yield statement returns one element of a collection at a time. The Yield statement is included in an iterator function or Get accessor, which perform custom iterations over a collection.

You consume an iterator function by using a For Each...Next Statement or a LINQ query. Each iteration of the For Each loop calls the iterator function. When a Yield statement is reached in the iterator function, expression is returned, and the current location in code is retained. Execution is restarted from that location the next time that the iterator function is called.

An implicit conversion must exist from the type of expression in the Yield statement to the return type of the iterator.

You can use an Exit Function or Return statement to end the iteration.

"Yield" is not a reserved word and has special meaning only when it is used in an Iterator function or Get accessor.

For more information about iterator functions and Get accessors, see Iterators.

Iterator Functions and Get Accessors

The declaration of an iterator function or Get accessor must meet the following requirements:

• It must include an Iterator modifier.

• The return type must be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.

• It cannot have any ByRef parameters.

An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor.

An iterator function can be an anonymous function. For more information, see Iterators.

Exception Handling

A Yield statement can be inside a Try block of a Try...Catch...Finally Statement. A Try block that has a Yield statement can have Catch blocks, and can have a Finally block.

A Yield statement cannot be inside a Catch block or a Finally block.

If the For Each body (outside of the iterator function) throws an exception, a Catch block in the iterator function is not executed, but a Finally block in the iterator function is executed. A Catch block inside an iterator function catches only exceptions that occur inside the iterator function.

Technical Implementation

The following code returns an IEnumerable (Of String) from an iterator function and then iterates through the elements of the IEnumerable (Of String).

Dim elements As IEnumerable(Of String) = MyIteratorFunction()  
    …  
For Each element As String In elements  
Next  

The call to MyIteratorFunction doesn't execute the body of the function. Instead the call returns an IEnumerable(Of String) into the elements variable.

On an iteration of the For Each loop, the MoveNext method is called for elements. This call executes the body of MyIteratorFunction until the next Yield statement is reached. The Yield statement returns an expression that determines not only the value of the element variable for consumption by the loop body but also the Current property of elements, which is an IEnumerable (Of String).

On each subsequent iteration of the For Each loop, the execution of the iterator body continues from where it left off, again stopping when it reaches a Yield statement. The For Each loop completes when the end of the iterator function or a Return or Exit Function statement is reached.

See also

• Statements

Source/Reference

• https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/a-e-statements
• https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/f-p-statements
• https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/error-statement
• https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/raiseevent-statement
• https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/throw-statement
• https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/statements/yield-statement