diff --git a/docs/toc.md b/docs/toc.md index 38162d89a0390..d3576a7e0999c 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -1090,6 +1090,8 @@ ##### [-quiet](visual-basic/reference/command-line-compiler/quiet.md) ##### [-recurse](visual-basic/reference/command-line-compiler/recurse.md) ##### [-reference](visual-basic/reference/command-line-compiler/reference.md) +##### [-refonly](visual-basic/reference/command-line-compiler/refonly-compiler-option.md) +##### [-refout](visual-basic/reference/command-line-compiler/refout-compiler-option.md) ##### [-removeintchecks](visual-basic/reference/command-line-compiler/removeintchecks.md) ##### [-resource](visual-basic/reference/command-line-compiler/resource.md) ##### [-rootnamespace](visual-basic/reference/command-line-compiler/rootnamespace.md) diff --git a/docs/visual-basic/getting-started/whats-new.md b/docs/visual-basic/getting-started/whats-new.md index 4768265bb12f7..aa2caa0211b5f 100644 --- a/docs/visual-basic/getting-started/whats-new.md +++ b/docs/visual-basic/getting-started/whats-new.md @@ -30,6 +30,9 @@ For new features, see [Visual Basic 15.5](#visual-basic-155) Visual Basic 15.3 For new features, see [Visual Basic 15.3](#visual-basic-153) +Visual Basic 2017 +For new features, see [Visual Basic 2017](#visual-basic-2017) + Visual Basic / Visual Studio .NET 2015 For new features, see [Visual Basic 14](#visual-basic-14) @@ -73,8 +76,7 @@ Visual Basic 2017 added support for the underscore character (`_`) as a digit se ```vb Dim number As Integer = &H_C305_F860 ``` -To use the under -score character as a leading separator, you must add the following element to your Visual Basic project (*.vbproj) file: +To use the underscore character as a leading separator, you must add the following element to your Visual Basic project (\*.vbproj) file: ```xml @@ -84,15 +86,19 @@ score character as a leading separator, you must add the following element to yo ## Visual Basic 15.3 -[Named tuple inference](../programming-guide/language-features/data-types/tuples.md#inferred-tuple-element-names) +[**Named tuple inference**](../programming-guide/language-features/data-types/tuples.md#inferred-tuple-element-names) When you assign the value of tuple elements from variables, Visual Basic infers the name of tuple elements from the corresponding variable names; you do not have to explicitly name a tuple element. The following example uses inference to create a tuple with three named elements, `state`, `stateName`, and `capital`. [!code-vb[Inferred tuple names](../../../samples/snippets/visualbasic/programming-guide/language-features/data-types/named-tuples/program.vb#2)] +**Additional compiler switches** + +The Visual Basic command-line compiler now supports the [**-refout**](../reference/command-line-compiler/refout-compiler-option.md) and [**-refonly**](../reference/command-line-compiler/refonly-compiler-option.md) compiler options to control the output of reference assemblies. **-refout** defines the output directory of the reference assembly, and **-refonly** specifies that only a reference assembly is to be output by compilation. + ## Visual Basic 2017 -[Tuples](../programming-guide/language-features/data-types/tuples.md) +[**Tuples**](../programming-guide/language-features/data-types/tuples.md) Tuples are a lightweight data structure that most commonly is used to return multiple values from a single method call. Ordinarily, to return multiple values from a method, you have to do one of the following: diff --git a/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-alphabetically.md b/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-alphabetically.md index 0375c8b22e39f..5da01d0e3f8fc 100644 --- a/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-alphabetically.md +++ b/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-alphabetically.md @@ -14,7 +14,9 @@ author: rpetrusha ms.author: ronpet --- # Visual Basic compiler options listed alphabetically -The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler is provided as an alternative to compiling programs from the [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] integrated development environment (IDE). The following is a list of the [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler options sorted alphabetically. +The Visual Basic command-line compiler is provided as an alternative to compiling programs from the [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] integrated development environment (IDE). The following is a list of the Visual Basic command-line compiler options sorted alphabetically. + +[!INCLUDE[compiler-options](~/includes/compiler-options.md)] |Option|Purpose| |------------|-------------| @@ -31,9 +33,9 @@ The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler is provide |[-define](../../../visual-basic/reference/command-line-compiler/define.md)|Defines symbols for conditional compilation.| |[-delaysign](../../../visual-basic/reference/command-line-compiler/delaysign.md)|Specifies whether the assembly will be fully or partially signed.| |[-doc](../../../visual-basic/reference/command-line-compiler/doc.md)|Processes documentation comments to an XML file.| -|[-errorreport](../../../visual-basic/reference/command-line-compiler/errorreport.md)|Specifies how the [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] compiler should report internal compiler errors.| +|[-errorreport](../../../visual-basic/reference/command-line-compiler/errorreport.md)|Specifies how the Visual Basic compiler should report internal compiler errors.| |[-filealign](../../../visual-basic/reference/command-line-compiler/filealign.md)|Specifies where to align the sections of the output file.| -|[-help](../../../visual-basic-reference/command-line-compiler/help.md)|Displays compiler options. This command is the same as specifying the `-?` option. No compilation occurs.| +|[-help](../../../visual-basic/reference/command-line-compiler/help.md)|Displays compiler options. This command is the same as specifying the `-?` option. No compilation occurs.| |[-highentropyva](../../../visual-basic/reference/command-line-compiler/highentropyva.md)|Indicates whether a particular executable supports high entropy Address Space Layout Randomization (ASLR).| |[-imports](../../../visual-basic/reference/command-line-compiler/imports.md)|Imports a namespace from a specified assembly.| |[-keycontainer](../../../visual-basic/reference/command-line-compiler/keycontainer.md)|Specifies a key container name for a key pair to give an assembly a strong name.| @@ -62,6 +64,8 @@ The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler is provide |[-quiet](../../../visual-basic/reference/command-line-compiler/quiet.md)|Prevents the compiler from displaying code for syntax-related errors and warnings.| |[-recurse](../../../visual-basic/reference/command-line-compiler/recurse.md)|Searches subdirectories for source files to compile.| |[-reference](../../../visual-basic/reference/command-line-compiler/reference.md)|Imports metadata from an assembly.| +|[-refonly](refonly-compiler-option.md)|Outputs only a reference assembly.| +|[-refout](refout-compiler-option.md)|Specifies the output path of a reference assembly.| |[-removeintchecks](../../../visual-basic/reference/command-line-compiler/removeintchecks.md)|Disables integer overflow checking.| |[-resource](../../../visual-basic/reference/command-line-compiler/resource.md)|Embeds a managed resource in an assembly.| |[-rootnamespace](../../../visual-basic/reference/command-line-compiler/rootnamespace.md)|Specifies a namespace for all type declarations.| diff --git a/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-by-category.md b/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-by-category.md index 8c714cf043d44..798cddffccf35 100644 --- a/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-by-category.md +++ b/docs/visual-basic/reference/command-line-compiler/compiler-options-listed-by-category.md @@ -14,7 +14,9 @@ author: rpetrusha ms.author: ronpet --- # Visual Basic compiler options listed by category -The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler is provided as an alternative to compiling programs from within the [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] integrated development environment (IDE). The following is a list of the [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler options sorted by functional category. +The Visual Basic command-line compiler is provided as an alternative to compiling programs from within the [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] integrated development environment (IDE). The following is a list of the Visual Basic command-line compiler options sorted by functional category. + +[!INCLUDE[compiler-options](~/includes/compiler-options.md)] ## Compiler output @@ -40,6 +42,8 @@ The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler is provide |[-doc](../../../visual-basic/reference/command-line-compiler/doc.md)|Process documentation comments to an XML file.| |[-netcf](../../../visual-basic/reference/command-line-compiler/netcf.md)|Sets the compiler to target the [!INCLUDE[Compact](~/includes/compact-md.md)].| |[-out](../../../visual-basic/reference/command-line-compiler/out.md)|Specifies an output file.| +|[-refonly](refonly-compiler-option.md)|Outputs only a reference assembly.| +|[-refout](refout-compiler-option.md)|Specifies the output path of a reference assembly.| |[-target](../../../visual-basic/reference/command-line-compiler/target.md)|Specifies the format of the output.| ## .NET assemblies @@ -108,7 +112,7 @@ The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler is provide |[@ (Specify Response File)](../../../visual-basic/reference/command-line-compiler/specify-response-file.md)|Specifies a response file.| |[-baseaddress](../../../visual-basic/reference/command-line-compiler/baseaddress.md)|Specifies the base address of a DLL.| |[-codepage](../../../visual-basic/reference/command-line-compiler/codepage.md)|Specifies the code page to use for all source code files in the compilation.| -|[-errorreport](../../../visual-basic/reference/command-line-compiler/errorreport.md)|Specifies how the [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] compiler should report internal compiler errors.| +|[-errorreport](../../../visual-basic/reference/command-line-compiler/errorreport.md)|Specifies how the Visual Basic compiler should report internal compiler errors.| |[-highentropyva](../../../visual-basic/reference/command-line-compiler/highentropyva.md)|Tells the Windows kernel whether a particular executable supports high entropy Address Space Layout Randomization (ASLR).| |[-main](../../../visual-basic/reference/command-line-compiler/main.md)|Specifies the class that contains the `Sub Main` procedure to use at startup.| |[-noconfig](../../../visual-basic/reference/command-line-compiler/noconfig.md)|Do not compile with Vbc.rsp| @@ -125,6 +129,6 @@ The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler is provide ## See Also [Visual Basic Compiler Options Listed Alphabetically](../../../visual-basic/reference/command-line-compiler/compiler-options-listed-alphabetically.md) - [Introduction to the Project Designer](http://msdn.microsoft.com/library/898dd854-c98d-430c-ba1b-a913ce3c73d7) + [Introduction to the Project Designer](https://msdn.microsoft.com/en-us/library/898dd854-c98d-430c-ba1b-a913ce3c73d7(v=vs.100)) [C# Compiler Options Listed Alphabetically](../../../csharp/language-reference/compiler-options/listed-alphabetically.md) [C# Compiler Options Listed by Category](../../../csharp/language-reference/compiler-options/listed-by-category.md) diff --git a/docs/visual-basic/reference/command-line-compiler/index.md b/docs/visual-basic/reference/command-line-compiler/index.md index 699cc67607fde..7b8ce427fa57a 100644 --- a/docs/visual-basic/reference/command-line-compiler/index.md +++ b/docs/visual-basic/reference/command-line-compiler/index.md @@ -19,7 +19,7 @@ ms.author: mairaw The Visual Basic command-line compiler provides an alternative to compiling programs from within the Visual Studio integrated development environment (IDE). This section contains descriptions for the Visual Basic compiler options. -Every compiler option is available in two forms: -option and /option. The Visual Basic documentation only shows the /option form. +[!INCLUDE[compiler-options](~/includes/compiler-options.md)] ## In this section diff --git a/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md b/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md new file mode 100644 index 0000000000000..49e4c75dd5dbd --- /dev/null +++ b/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md @@ -0,0 +1,43 @@ +--- +title: "-refonly (Visual Basic)" +ms.date: 03/16/2018 +ms.prod: .net +ms.technology: + - "devlang-visual-basic" +ms.topic: "article" +f1_keywords: + - "-refonly" +helpviewer_keywords: + - "/refonly compiler option [Visual Basic]" + - "-refonly compiler option [Visual Basic]" + - "refonly compiler option [Visual Basic]" +author: "rpetrusha" +ms.author: "ronpet" +--- + +# -refonly (Visual Basic) + +The **-refonly** option indicates that the primary output of the compilation should be a reference assembly instead of an implementation assembly. The `-refonly` parameter silently disables outputting PDBs, as reference assemblies cannot be executed. + +[!INCLUDE[compiler-options](~/includes/compiler-options.md)] + +## Syntax + +```console +-refonly +``` + +## Remarks + +Visual Basic supports the `-refout` switch starting with version 15.3. + +Reference assemblies are metadata-only assemblies that contain metadata but no implementation code. They include type and member information for everything except anonymous types. The reason for using `throw null` bodies (as opposed to no bodies) is so that PEVerify could run and pass (thus validating the completeness of the metadata). + +Reference assemblies include an assembly-level [ReferenceAssembly](xref:System.Runtime.CompilerServices.ReferenceAssemblyAttribute) attribute. This attribute may be specified in source (then the compiler won't need to synthesize it). Because of this attribute, runtimes will refuse to load reference assemblies for execution (but they can still be loaded in a reflection-only context). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only; otherwise, the runtime throws a . + +The `-refonly` and [`-refout`](refout-compiler-option.md) options are mutually exclusive. + +## See also +[-refout](refout-compiler-option.md) +[Visual Basic Command-Line Compiler](index.md) +[Sample Compilation Command Lines](sample-compilation-command-lines.md) diff --git a/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md b/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md new file mode 100644 index 0000000000000..30052dc88ad2b --- /dev/null +++ b/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md @@ -0,0 +1,49 @@ +--- +title: "-refout (Visual Basic)" +ms.date: 03/16/2018 +ms.prod: .net +ms.technology: + - "devlang-visual-basic" +ms.topic: "article" +f1_keywords: + - "/refout" +helpviewer_keywords: + - "refout compiler option [Visual Basic]" + - "/refout compiler option [Visual Basic]" + - "-refout compiler option [Visual Basic]" +author: "rpetrusha" +ms.author: "ronpet" +--- + +# -refout (Visual Basic) + +The **-refout** option specifies a file path where the reference assembly should be output. + +[!INCLUDE[compiler-options](~/includes/compiler-options.md)] + +## Syntax + +```console +-refout:filepath +``` + +## Arguments + + `filepath` +The path and filename of the reference assembly. It should generally be in a sub-folder of the primary assembly. The recommended convention (used by MSBuild) is to place the reference assembly in a "ref/" sub-folder relative to the primary assembly. All folders in `filepath` must exist; the compiler does not create them. + +## Remarks + +Visual Basic supports the `-refout` switch starting with version 15.3. + +Reference assemblies are metadata-only assemblies that contain metadata but no implementation code. They include type and member information for everything except anonymous types. Their method bodies are replaced with a single `throw null` statement. The reason for using `throw null` method bodies (as opposed to no bodies) is so that PEVerify can run and pass (thus validating the completeness of the metadata). + +Reference assemblies include an assembly-level [ReferenceAssembly](xref:System.Runtime.CompilerServices.ReferenceAssemblyAttribute) attribute. This attribute may be specified in source (then the compiler won't need to synthesize it). Because of this attribute, runtimes refuse to load reference assemblies for execution (but they can still be loaded in a reflection-only context). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only; otherwise, the runtime throws a . + +The `-refout` and [`-refonly`](refonly-compiler-option.md) options are mutually exclusive. + +## See Also +[-refonly](refonly-compiler-option.md) +[Visual Basic Command-Line Compiler](index.md) +[Sample Compilation Command Lines](sample-compilation-command-lines.md) + diff --git a/docs/visual-basic/reference/command-line-compiler/sample-compilation-command-lines.md b/docs/visual-basic/reference/command-line-compiler/sample-compilation-command-lines.md index dcd89b5c77983..c0974ac721b3e 100644 --- a/docs/visual-basic/reference/command-line-compiler/sample-compilation-command-lines.md +++ b/docs/visual-basic/reference/command-line-compiler/sample-compilation-command-lines.md @@ -18,9 +18,9 @@ author: rpetrusha ms.author: ronpet --- # Sample compilation command lines (Visual Basic) -As an alternative to compiling [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] programs from within [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)], you can compile from the command line to produce executable (.exe) files or dynamic-link library (.dll) files. +As an alternative to compiling Visual Basic programs from within [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)], you can compile from the command line to produce executable (.exe) files or dynamic-link library (.dll) files. - The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] command-line compiler supports a complete set of options that control input and output files, assemblies, and debug and preprocessor options. Each option is available in two interchangeable forms: `-option` and `/option`. This documentation shows only the `-option` form. + The Visual Basic command-line compiler supports a complete set of options that control input and output files, assemblies, and debug and preprocessor options. Each option is available in two interchangeable forms: `-option` and `/option`. This documentation shows only the `-option` form. The following table lists some sample command lines you can modify for your own use. @@ -29,14 +29,13 @@ As an alternative to compiling [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] progr |Compile File.vb and create File.exe|`vbc -reference:Microsoft.VisualBasic.dll File.vb`| |Compile File.vb and create File.dll|`vbc -target:library File.vb`| |Compile File.vb and create My.exe|`vbc -out:My.exe File.vb`| -|Compile all [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] files in the current directory, with optimizations on and the `DEBUG` symbol defined, producing File2.exe|`vbc -define:DEBUG=1 -optimize -out:File2.exe *.vb`| -|Compile all [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] files in the current directory, producing a debug version of File2.dll without displaying the logo or warnings|`vbc -target:library -out:File2.dll -nowarn -nologo -debug *.vb`| -|Compile all [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] files in the current directory to Something.dll|`vbc -target:library -out:Something.dll *.vb`| - - When compiling from the command line, you must explicitly reference the Microsoft [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] run-time library through the `-reference` compiler option. +|Compile File.vb and create both a library and a reference assembly named File.dll|`vbc -target:library -ref:.\debug\bin\ref\file.dll File.vb`| +|Compile all Visual Basic files in the current directory, with optimizations on and the `DEBUG` symbol defined, producing File2.exe|`vbc -define:DEBUG=1 -optimize -out:File2.exe *.vb`| +|Compile all Visual Basic files in the current directory, producing a debug version of File2.dll without displaying the logo or warnings|`vbc -target:library -out:File2.dll -nowarn -nologo -debug *.vb`| +|Compile all Visual Basic files in the current directory to Something.dll|`vbc -target:library -out:Something.dll *.vb`| > [!TIP] -> When you build a project by using the Visual Studio IDE, you can display information about the associated **vbc** command with its compiler options in the output window. To display this information, open the [Options Dialog Box, Projects and Solutions, Build and Run](/visualstudio/ide/reference/options-dialog-box-projects-and-solutions-build-and-run), and then set the **MSBuild project build output verbosity** to **Normal** or a higher level of verbosity. For more information, see [How to: View, Save, and Configure Build Log Files](http://msdn.microsoft.com/library/75d38b76-26d6-4f43-bbe7-cbacd7cc81e7). +> When you build a project by using the Visual Studio IDE, you can display information about the associated **vbc** command with its compiler options in the output window. To display this information, open the [Options Dialog Box, Projects and Solutions, Build and Run](/visualstudio/ide/reference/options-dialog-box-projects-and-solutions-build-and-run), and then set the **MSBuild project build output verbosity** to **Normal** or a higher level of verbosity. ## See Also [Visual Basic Command-Line Compiler](../../../visual-basic/reference/command-line-compiler/index.md) diff --git a/xml/System/BadImageFormatException.xml b/xml/System/BadImageFormatException.xml index fdd5122a688ca..8b50850b33d39 100644 --- a/xml/System/BadImageFormatException.xml +++ b/xml/System/BadImageFormatException.xml @@ -39,17 +39,22 @@ ## Remarks This exception is thrown when the file format of a dynamic link library (.dll file) or an executable (.exe file) doesn’t conform to the format that the common language runtime expects. In particular, the exception is thrown under the following conditions: -- An earlier version of a .NET Framework utility, such as ILDasm.exe or installutil.exe, is used with an assembly that was developed with a later version of the .NET Framework. +- An earlier version of a .NET Framework utility, such as ILDasm.exe or installutil.exe, is used with an assembly that was developed with a later version of the .NET Framework. To address this exception, use the version of the tool that corresponds to the version of the .NET Framework that was used to develop the assembly. This may require modifying the `Path` environment variable or providing a fully qualified path to the correct executable. -- You try to load an unmanaged dynamic link library or executable (such as a Windows system DLL) as if it were a .NET Framework assembly. The following example illustrates this by using the method to load Kernel32.dll. +- You are trying to load an unmanaged dynamic link library or executable (such as a Windows system DLL) as if it were a .NET Framework assembly. The following example illustrates this by using the method to load Kernel32.dll. [!code-csharp[System.BadImageFormatException.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.badimageformatexception.class/cs/condition1.cs#1)] [!code-vb[System.BadImageFormatException.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.badimageformatexception.class/vb/condition1.vb#1)] To address this exception, access the methods defined in the DLL by using the features provided by your development language, such as the `Declare` statement in Visual Basic or the attribute with the `extern` keyword in C#. +- You are trying to load a reference assembly in a context other than the reflection-only context. You can address this issue in either of two ways: + + - You can load the implementation assembly rather than the reference assembly. + - You can load the reference assembly in the reflection-only context by calling the method. + - A DLL or executable is loaded as a 64-bit assembly, but it contains 32-bit features or resources. For example, it relies on COM interop or calls methods in a 32-bit dynamic link library. To address this exception, set the project's **Platform target** property to x86 (instead of x64 or AnyCPU) and recompile.