From 7deb311d2271fbec84d678aeefd21f79b735c1f5 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 15 Mar 2018 15:18:08 -0700 Subject: [PATCH 1/6] Preliminary checkin --- .../refonly-compiler-option.md | 46 ++++++++++++++++++ .../refout-compiler-option.md | 47 +++++++++++++++++++ xml/System/BadImageFormatException.xml | 5 ++ 3 files changed, 98 insertions(+) create mode 100644 docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md create mode 100644 docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md 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..de6bfd6eccb8d --- /dev/null +++ b/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md @@ -0,0 +1,46 @@ +--- +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 a reference assembly should be output instead of an implementation assembly, as the primary output. The `-refonly` parameter silently disables outputting PDBs, as reference assemblies cannot be executed. + +## Syntax + +```console +-refonly +``` + +## Remarks + +Metadata-only assemblies have their method bodies replaced with a single `throw null` body, but include all members 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` 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 reflection-only mode). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only, otherwise they will receive a typeload error from the runtime. + +Reference assemblies further remove metadata (private members) from metadata-only assemblies: + +- A reference assembly only has references for what it needs in the API surface. The real assembly may have additional references related to specific implementations. For instance, the reference assembly for `class C { private void M() { dynamic d = 1; ... } }` does not reference any types required for `dynamic`. +- Private function-members (methods, properties, and events) are removed in cases where their removal doesn't observably impact compilation. If there are no `InternalsVisibleTo` attributes, do the same for internal function-members. +- But all types (including private or nested types) are kept in reference assemblies. All attributes are kept (even internal ones). +- All virtual methods are kept. Explicit interface implementations are kept. Explicitly implemented properties and events are kept, as their accessors are virtual (and are therefore kept). +- All fields of a struct are kept. (This is a candidate for post-C#-7.1 refinement) + +The `-refonly` and [`-refout`](refout-compiler-option.md) options are mutually exclusive. + +## See also + [C# Compiler Options](../../../csharp/language-reference/compiler-options/index.md) + [Managing Project and Solution Properties](/visualstudio/ide/managing-project-and-solution-properties) 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..f5dfaf7f8dd26 --- /dev/null +++ b/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md @@ -0,0 +1,47 @@ +--- +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. + +## Syntax + +```console +-refout:filepath +``` + +## Arguments + + `filepath` +The path and filename of the reference assembly. It should generally be located 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 contain metadata but no implementation code; 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 will refuse to load reference assemblies for execution (but they can still be loaded in reflection-only mode). 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](../../../visual-basic/reference/command-line-compiler/index.md) +[Sample Compilation Command Lines](../../../visual-basic/reference/command-line-compiler/sample-compilation-command-lines.md) + diff --git a/xml/System/BadImageFormatException.xml b/xml/System/BadImageFormatException.xml index fdd5122a688ca..3bc1fbcf3554a 100644 --- a/xml/System/BadImageFormatException.xml +++ b/xml/System/BadImageFormatException.xml @@ -50,6 +50,11 @@ 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 attempting to load a reference assembly 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. From c2095859635aad8bd2b6d2f0b8837326cfe90193 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 21 Mar 2018 16:34:21 -0700 Subject: [PATCH 2/6] Updated --- .../command-line-compiler/refout-compiler-option.md | 6 +++--- xml/System/BadImageFormatException.xml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) 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 index f5dfaf7f8dd26..01a833bc33733 100644 --- a/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md +++ b/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md @@ -28,15 +28,15 @@ The **-refout** option specifies a file path where the reference assembly should ## Arguments `filepath` -The path and filename of the reference assembly. It should generally be located 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. +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 contain metadata but no implementation code; 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 are metadata-only assemblies 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 will refuse to load reference assemblies for execution (but they can still be loaded in reflection-only mode). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only; otherwise the runtime throws a . +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. diff --git a/xml/System/BadImageFormatException.xml b/xml/System/BadImageFormatException.xml index 3bc1fbcf3554a..8b50850b33d39 100644 --- a/xml/System/BadImageFormatException.xml +++ b/xml/System/BadImageFormatException.xml @@ -39,18 +39,18 @@ ## 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 attempting to load a reference assembly a context other than the reflection-only context. You can address this issue in either of two ways: +- 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. From e08e50102df3edc07a37eff1fbc5b1d2fc6d5e07 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 21 Mar 2018 17:16:24 -0700 Subject: [PATCH 3/6] Documented two new compiler switches --- docs/toc.md | 2 ++ .../visual-basic/getting-started/whats-new.md | 7 +++++++ .../compiler-options-listed-alphabetically.md | 2 ++ .../compiler-options-listed-by-category.md | 2 ++ .../refonly-compiler-option.md | 19 +++++++------------ .../refout-compiler-option.md | 10 +++++----- .../sample-compilation-command-lines.md | 15 +++++++-------- 7 files changed, 32 insertions(+), 25 deletions(-) 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..693260cb66436 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) @@ -90,6 +93,10 @@ When you assign the value of tuple elements from variables, Visual Basic infers [!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) 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..c15cffe64d9f8 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 @@ -62,6 +62,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..aae8a957f048a 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 @@ -40,6 +40,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 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 index de6bfd6eccb8d..565810e1b456c 100644 --- a/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md +++ b/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md @@ -17,7 +17,7 @@ ms.author: "ronpet" # -refonly (Visual Basic) -The **-refonly** option indicates that a reference assembly should be output instead of an implementation assembly, as the primary output. The `-refonly` parameter silently disables outputting PDBs, as reference assemblies cannot be executed. +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. ## Syntax @@ -27,20 +27,15 @@ The **-refonly** option indicates that a reference assembly should be output ins ## Remarks -Metadata-only assemblies have their method bodies replaced with a single `throw null` body, but include all members 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). +Visual Basic supports the `-refout` switch starting with version 15.3. -Reference assemblies include an assembly-level `ReferenceAssembly` 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 reflection-only mode). Tools that reflect on assemblies need to ensure they load reference assemblies as reflection-only, otherwise they will receive a typeload error from the runtime. +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 further remove metadata (private members) from metadata-only assemblies: - -- A reference assembly only has references for what it needs in the API surface. The real assembly may have additional references related to specific implementations. For instance, the reference assembly for `class C { private void M() { dynamic d = 1; ... } }` does not reference any types required for `dynamic`. -- Private function-members (methods, properties, and events) are removed in cases where their removal doesn't observably impact compilation. If there are no `InternalsVisibleTo` attributes, do the same for internal function-members. -- But all types (including private or nested types) are kept in reference assemblies. All attributes are kept (even internal ones). -- All virtual methods are kept. Explicit interface implementations are kept. Explicitly implemented properties and events are kept, as their accessors are virtual (and are therefore kept). -- All fields of a struct are kept. (This is a candidate for post-C#-7.1 refinement) +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 - [C# Compiler Options](../../../csharp/language-reference/compiler-options/index.md) - [Managing Project and Solution Properties](/visualstudio/ide/managing-project-and-solution-properties) +[-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 index 01a833bc33733..7d92e12a170ef 100644 --- a/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md +++ b/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md @@ -32,16 +32,16 @@ The path and filename of the reference assembly. It should generally be in a sub ## Remarks -Visual Basic supports the -refout switch starting with version 15.3. +Visual Basic supports the `-refout` switch starting with version 15.3. -Reference assemblies are metadata-only assemblies 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 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](../../../visual-basic/reference/command-line-compiler/index.md) -[Sample Compilation Command Lines](../../../visual-basic/reference/command-line-compiler/sample-compilation-command-lines.md) +[-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) From f9a93d969ed924aed358ea0ff2c8b11e68d0e0ef Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 22 Mar 2018 09:13:47 -0700 Subject: [PATCH 4/6] Included compiler-options.md --- .../compiler-options-listed-alphabetically.md | 6 ++++-- .../compiler-options-listed-by-category.md | 6 ++++-- docs/visual-basic/reference/command-line-compiler/index.md | 2 +- .../command-line-compiler/refonly-compiler-option.md | 2 ++ .../command-line-compiler/refout-compiler-option.md | 2 ++ 5 files changed, 13 insertions(+), 5 deletions(-) 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 c15cffe64d9f8..a47735a8dbc84 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,7 +33,7 @@ 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.| |[-highentropyva](../../../visual-basic/reference/command-line-compiler/highentropyva.md)|Indicates whether a particular executable supports high entropy Address Space Layout Randomization (ASLR).| 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 aae8a957f048a..133b6023a4169 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 @@ -110,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| 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 index 565810e1b456c..49e4c75dd5dbd 100644 --- a/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md +++ b/docs/visual-basic/reference/command-line-compiler/refonly-compiler-option.md @@ -19,6 +19,8 @@ ms.author: "ronpet" 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 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 index 7d92e12a170ef..30052dc88ad2b 100644 --- a/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md +++ b/docs/visual-basic/reference/command-line-compiler/refout-compiler-option.md @@ -19,6 +19,8 @@ ms.author: "ronpet" The **-refout** option specifies a file path where the reference assembly should be output. +[!INCLUDE[compiler-options](~/includes/compiler-options.md)] + ## Syntax ```console From aee4d0f47480eb7e87251468e598e2d10b35f3da Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 22 Mar 2018 09:20:52 -0700 Subject: [PATCH 5/6] Corrected typo, bad formatting --- docs/visual-basic/getting-started/whats-new.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/visual-basic/getting-started/whats-new.md b/docs/visual-basic/getting-started/whats-new.md index 693260cb66436..6939729fa85a9 100644 --- a/docs/visual-basic/getting-started/whats-new.md +++ b/docs/visual-basic/getting-started/whats-new.md @@ -30,7 +30,7 @@ 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 +Visual Basic 2017 For new features, see [Visual Basic 2017](#visual-basic-2017) Visual Basic / Visual Studio .NET 2015 @@ -76,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 From e0d9f9e34708dccb2e3e5438a622b2495b0b2877 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 22 Mar 2018 10:59:15 -0700 Subject: [PATCH 6/6] fixed links and formatting --- docs/visual-basic/getting-started/whats-new.md | 6 +++--- .../compiler-options-listed-alphabetically.md | 2 +- .../compiler-options-listed-by-category.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/visual-basic/getting-started/whats-new.md b/docs/visual-basic/getting-started/whats-new.md index 6939729fa85a9..aa2caa0211b5f 100644 --- a/docs/visual-basic/getting-started/whats-new.md +++ b/docs/visual-basic/getting-started/whats-new.md @@ -86,19 +86,19 @@ To use the underscore character as a leading separator, you must add the followi ## 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 +**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 a47735a8dbc84..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 @@ -35,7 +35,7 @@ The Visual Basic command-line compiler is provided as an alternative to compilin |[-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 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.| 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 133b6023a4169..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 @@ -129,6 +129,6 @@ The Visual Basic command-line compiler is provided as an alternative to compilin ## 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)