From 093e5301e272a5d5569791ab1e80158a567186b0 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Thu, 12 Sep 2019 13:24:24 +0500 Subject: [PATCH 01/20] Add reference assemblies topic Sources: - https://github.com/dotnet/standard/blob/master/docs/history/evolution-of-design-time-assemblies.md - https://github.com/dotnet/roslyn/blob/master/docs/features/refout.md --- .../standard/assembly/reference-assemblies.md | 66 +++++++++++++++++++ docs/standard/assembly/toc.yml | 4 +- 2 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 docs/standard/assembly/reference-assemblies.md diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md new file mode 100644 index 0000000000000..65ba794726384 --- /dev/null +++ b/docs/standard/assembly/reference-assemblies.md @@ -0,0 +1,66 @@ +--- +title: "Reference assemblies" +description: "Learn about reference assemblies, a special type of assemblies in .NET that contain only the library's public API surface" +author: MSDN-WhiteKnight +ms.author: ronpet +ms.date: 09/12/2019 +ms.technology: dotnet-standard +--- +# Reference assemblies + +*Reference assemblies* are a special type of assemblies that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools (hence the name), but exclude all method definitions as well as declarations of private members that have no observable impact on their API contract. In contrast, regular assemblies are called *implementation assemblies*. Reference assemblies cannot be loaded for execution, but they can be passed as the compiler input in the same way as implementation assemblies. Reference assemblies are usually distributed with the Software Development Kit (SDK) of the particular platform or library, a special software component installed only on the developer machines. + +Using reference assemblies enables developers to build programs targeting specific library version without having full implementation assembly for that version. Suppose, you have only the latest version of some library on your machine, but want to build the program targeting a machine with the earlier version of that library. If you compile directly against the implementation assembly, you might inadvertedly use API members that aren't available in the earlier version and only find this mistake when testing the program on the target machine. If you compile against the reference assembly for the earlier version, you get a compile time error in this case. + +## Using reference assemblies + +To use certain API from your project you must add references to its assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and meant to be used by API designers (in other words, not taking dependency on implementation details). + +Reference assemblies for .NET Framework standard library are distributed with Targeting Packs. You can obtain them by downloading a standalone isntaller or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core standard library are managed as NuGet packages. For example, [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../../core/packages.md) in .NET Core guide. + +When you add reference to .NET Framework standard library assemblies in Visual Studio using **Add reference** dialog, you don't have to specify assembly files manually; you select an assembly from the list and Visual Studio automatically finds a reference assembly file corresponding to the target framework version selected in your project. When you add reference to these assemblies in the command line using `-reference` compiler option ([in C#](../../../csharp/language-reference/compiler-options/reference-compiler-option.md), [in Visual Basic](../../../visual-basic/reference/command-line-compiler/reference.md)) or in Roslyn API using method, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in `%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework directory`. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under `%ProgramFiles%\dotnet\sdk\` on Windows, `/usr/share/dotnet/sdk/` on Linux, or `/usr/local/share/dotnet/sdk` on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locating reference assembly files for the particular target platform. + +Reference assemblies cannot be loaded for execution, trying to do so results in . However, they still can be loaded into the reflection-only context (using +) method, if you need to examine their contents. + +## Generating reference assemblies + +Generating reference assemblies for your libraries can be useful when your library consumers often need to build their programs against many different versions of the library (that is, when you need to implement a feature similar to .NET Framework Targeting Packs mentioned above for your own project). Distributing implementation assemblies for all these versions might be impractical due to their large size. Reference assemblies are smaller in size, so distributing them as a part of your library's SDK reduces the download size and saves the disk space. + +IDEs and build tools also can take advantage of reference assemblies to reduce the build time in case of a large solution consisting of multiple class libraries. Reference assembly doesn't change when programmer changes private implementation details of a class library without affecting its public API, so projects that take dependency on it via the reference assembly don't have to be rebuilt on each of these changes. + +You can generate reference assemblies: + +- In MSBuild project by using `ProduceReferenceAssembly` [project property](/visualstudio/msbuild/common-msbuild-project-properties) +- When compiling program from command line, by specifiying `-refonly` ([in C#](../../../csharp/language-reference/compiler-options/refonly-compiler-option.md), [in Visual Basic](../../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([in C#](../../../csharp/language-reference/compiler-options/refout-compiler-option.md), [in Visual Basic](../../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options +- When using Roslyn API, by setting to `true` and to `false` in an object passed to method. + +If you want to distribute reference assemblies with NuGet packages, you must include them in "ref\" subdirectory under the package directory, instead of "lib\" subdirectory used for implementation assemblies. + +## Reference assemblies structure + +Technically, reference assemblies are metadata-only assemblies with certain types of private members excluded. + +*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](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 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](xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute) 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) + +Exact reference assembly structure details depend on the compiler version. Newer versions may choose to exclude more metadata if it is determined as not affecting the public API surface. + +> [!NOTE] +> Information in this section is applicable only to reference assemblies generated by Roslyn compilers starting from C# version 7.1 or Visual Basic version 15.3. Reference assemblies for .NET Framework versions released before that time can have different structure in some details. For example, they might have totally empty method bodies instead of the mentioned single `throw null` body. But the general principle still applies: they don't have usable method implementations and contain metadata only for members which have observable impact from public API perspective. + +## See also + +- [Assemblies in the Common Language Runtime](/dotnet/framework/app-domains/assemblies-in-the-common-language-runtime) +- [Framework targeting overview](/visualstudio/ide/visual-studio-multi-targeting-overview) +- [How to: Add or remove references by using the Reference Manager](/visualstudio/ide/how-to-add-or-remove-references-by-using-the-reference-manager) +- [Creating Assemblies](/dotnet/framework/app-domains/create-assemblies) diff --git a/docs/standard/assembly/toc.yml b/docs/standard/assembly/toc.yml index a2160ee98a5a8..f30ecaba7502f 100644 --- a/docs/standard/assembly/toc.yml +++ b/docs/standard/assembly/toc.yml @@ -8,4 +8,6 @@ - name: .NET assembly file format href: file-format.md - name: "How to use and debug assembly unloadability in .NET Core" - href: unloadability-howto.md \ No newline at end of file + href: unloadability-howto.md + - name: Reference assemblies + href: reference-assemblies.md From 3dfbda7b1f2d141c0adf785aae23f535979721f2 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Thu, 12 Sep 2019 13:29:31 +0500 Subject: [PATCH 02/20] fix link --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 65ba794726384..a151c9136206b 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -16,7 +16,7 @@ Using reference assemblies enables developers to build programs targeting specif To use certain API from your project you must add references to its assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and meant to be used by API designers (in other words, not taking dependency on implementation details). -Reference assemblies for .NET Framework standard library are distributed with Targeting Packs. You can obtain them by downloading a standalone isntaller or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core standard library are managed as NuGet packages. For example, [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../../core/packages.md) in .NET Core guide. +Reference assemblies for .NET Framework standard library are distributed with Targeting Packs. You can obtain them by downloading a standalone isntaller or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core standard library are managed as NuGet packages. For example, [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../../core/packages.md) in .NET Core guide. When you add reference to .NET Framework standard library assemblies in Visual Studio using **Add reference** dialog, you don't have to specify assembly files manually; you select an assembly from the list and Visual Studio automatically finds a reference assembly file corresponding to the target framework version selected in your project. When you add reference to these assemblies in the command line using `-reference` compiler option ([in C#](../../../csharp/language-reference/compiler-options/reference-compiler-option.md), [in Visual Basic](../../../visual-basic/reference/command-line-compiler/reference.md)) or in Roslyn API using method, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in `%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework directory`. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under `%ProgramFiles%\dotnet\sdk\` on Windows, `/usr/share/dotnet/sdk/` on Linux, or `/usr/local/share/dotnet/sdk` on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locating reference assembly files for the particular target platform. From 48f44d05291e53fad0803a7ae2b1a10a4d2b53fc Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Thu, 12 Sep 2019 13:32:32 +0500 Subject: [PATCH 03/20] fix links --- docs/standard/assembly/reference-assemblies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index a151c9136206b..3a0239c56b16d 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -16,9 +16,9 @@ Using reference assemblies enables developers to build programs targeting specif To use certain API from your project you must add references to its assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and meant to be used by API designers (in other words, not taking dependency on implementation details). -Reference assemblies for .NET Framework standard library are distributed with Targeting Packs. You can obtain them by downloading a standalone isntaller or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core standard library are managed as NuGet packages. For example, [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../../core/packages.md) in .NET Core guide. +Reference assemblies for .NET Framework standard library are distributed with Targeting Packs. You can obtain them by downloading a standalone isntaller or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core standard library are managed as NuGet packages. For example, [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in .NET Core guide. -When you add reference to .NET Framework standard library assemblies in Visual Studio using **Add reference** dialog, you don't have to specify assembly files manually; you select an assembly from the list and Visual Studio automatically finds a reference assembly file corresponding to the target framework version selected in your project. When you add reference to these assemblies in the command line using `-reference` compiler option ([in C#](../../../csharp/language-reference/compiler-options/reference-compiler-option.md), [in Visual Basic](../../../visual-basic/reference/command-line-compiler/reference.md)) or in Roslyn API using method, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in `%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework directory`. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under `%ProgramFiles%\dotnet\sdk\` on Windows, `/usr/share/dotnet/sdk/` on Linux, or `/usr/local/share/dotnet/sdk` on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locating reference assembly files for the particular target platform. +When you add reference to .NET Framework standard library assemblies in Visual Studio using **Add reference** dialog, you don't have to specify assembly files manually; you select an assembly from the list and Visual Studio automatically finds a reference assembly file corresponding to the target framework version selected in your project. When you add reference to these assemblies in the command line using `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or in Roslyn API using method, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in `%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework directory`. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under `%ProgramFiles%\dotnet\sdk\` on Windows, `/usr/share/dotnet/sdk/` on Linux, or `/usr/local/share/dotnet/sdk` on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locating reference assembly files for the particular target platform. Reference assemblies cannot be loaded for execution, trying to do so results in . However, they still can be loaded into the reflection-only context (using ) method, if you need to examine their contents. @@ -32,7 +32,7 @@ IDEs and build tools also can take advantage of reference assemblies to reduce t You can generate reference assemblies: - In MSBuild project by using `ProduceReferenceAssembly` [project property](/visualstudio/msbuild/common-msbuild-project-properties) -- When compiling program from command line, by specifiying `-refonly` ([in C#](../../../csharp/language-reference/compiler-options/refonly-compiler-option.md), [in Visual Basic](../../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([in C#](../../../csharp/language-reference/compiler-options/refout-compiler-option.md), [in Visual Basic](../../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options +- When compiling program from command line, by specifiying `-refonly` ([in C#](../../csharp/language-reference/compiler-options/refonly-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([in C#](../../csharp/language-reference/compiler-options/refout-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options - When using Roslyn API, by setting to `true` and to `false` in an object passed to method. If you want to distribute reference assemblies with NuGet packages, you must include them in "ref\" subdirectory under the package directory, instead of "lib\" subdirectory used for implementation assemblies. From 0336d4a1cf7afa1e71651d055559d43533db4743 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Thu, 12 Sep 2019 13:36:48 +0500 Subject: [PATCH 04/20] escape backslash --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 3a0239c56b16d..522e87673af14 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -35,7 +35,7 @@ You can generate reference assemblies: - When compiling program from command line, by specifiying `-refonly` ([in C#](../../csharp/language-reference/compiler-options/refonly-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([in C#](../../csharp/language-reference/compiler-options/refout-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options - When using Roslyn API, by setting to `true` and to `false` in an object passed to method. -If you want to distribute reference assemblies with NuGet packages, you must include them in "ref\" subdirectory under the package directory, instead of "lib\" subdirectory used for implementation assemblies. +If you want to distribute reference assemblies with NuGet packages, you must include them in "ref\\" subdirectory under the package directory, instead of "lib\\" subdirectory used for implementation assemblies. ## Reference assemblies structure From ec01febf70c50d4c21392761ea2b6de437457b0a Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Thu, 12 Sep 2019 13:43:56 +0500 Subject: [PATCH 05/20] Add link ti index.md --- docs/standard/assembly/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/standard/assembly/index.md b/docs/standard/assembly/index.md index e0f2979d9486a..c928223b3cb5d 100644 --- a/docs/standard/assembly/index.md +++ b/docs/standard/assembly/index.md @@ -54,6 +54,7 @@ Compile your application by building it in Visual Studio, by building it from th - [.NET assembly file format](file-format.md) - [Assemblies in the Common Language Runtime](../../framework/app-domains/assemblies-in-the-common-language-runtime.md) - [Friend Assemblies](friend-assemblies.md) +- [Reference Assemblies](reference-assemblies.md) - [How to: Load and Unload Assemblies (C#)](../../csharp/programming-guide/concepts/assemblies-gac/how-to-load-and-unload-assemblies.md) - [How to: Load and Unload Assemblies (Visual Basic)](../../visual-basic/programming-guide/concepts/assemblies-gac/how-to-load-and-unload-assemblies.md) - [How to: Use and Debug Assembly Unloadability in .NET Core](unloadability-howto.md) From 6cee6a74a2ee9b89364cc4646e4d53977bbfaa5f Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Fri, 13 Sep 2019 13:03:03 +0500 Subject: [PATCH 06/20] Apply suggestions from code review Co-Authored-By: Ron Petrusha --- docs/standard/assembly/index.md | 2 +- .../standard/assembly/reference-assemblies.md | 39 +++++++++++-------- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/standard/assembly/index.md b/docs/standard/assembly/index.md index 36e1efef955b3..59abab2a2bd05 100644 --- a/docs/standard/assembly/index.md +++ b/docs/standard/assembly/index.md @@ -110,7 +110,7 @@ In C#, you can use two versions of the same assembly in a single application. Fo - [.NET assembly file format](file-format.md) - [Assemblies in .NET](index.md) - [Friend assemblies](friend.md) -- [Reference Assemblies](reference-assemblies.md) +- [Reference assemblies](reference-assemblies.md) - [How to: Load and unload assemblies](load-unload.md) - [How to: Use and debug assembly unloadability in .NET Core](unloadability.md) - [How to: Determine if a file is an assembly](identify.md) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 522e87673af14..52d1a827fbfbe 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -8,55 +8,60 @@ ms.technology: dotnet-standard --- # Reference assemblies -*Reference assemblies* are a special type of assemblies that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools (hence the name), but exclude all method definitions as well as declarations of private members that have no observable impact on their API contract. In contrast, regular assemblies are called *implementation assemblies*. Reference assemblies cannot be loaded for execution, but they can be passed as the compiler input in the same way as implementation assemblies. Reference assemblies are usually distributed with the Software Development Kit (SDK) of the particular platform or library, a special software component installed only on the developer machines. +*Reference assemblies* are a special type of assembly that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools (hence the name), but exclude all member implementations as well as declarations of private members that have no observable impact on their API contract. In contrast, regular assemblies are called *implementation assemblies*. -Using reference assemblies enables developers to build programs targeting specific library version without having full implementation assembly for that version. Suppose, you have only the latest version of some library on your machine, but want to build the program targeting a machine with the earlier version of that library. If you compile directly against the implementation assembly, you might inadvertedly use API members that aren't available in the earlier version and only find this mistake when testing the program on the target machine. If you compile against the reference assembly for the earlier version, you get a compile time error in this case. +Reference assemblies cannot be loaded for execution, but they can be passed as compiler input in the same way as implementation assemblies. Reference assemblies are usually distributed with the Software Development Kit (SDK) of a particular platform or library, a special software component installed only on developer machines. + +Using a reference assembly enables developers to build programs that target a specific library version without having the full implementation assembly for that version. Suppose, you have only the latest version of some library on your machine, but you want to build a program that targets a machine with an earlier version of that library. If you compile directly against the implementation assembly, you might inadvertently use API members that aren't available in the earlier version, and you'll only find this mistake when testing the program on the target machine. If you compile against the reference assembly for the earlier version, you'll immediately get a compile-time error. ## Using reference assemblies -To use certain API from your project you must add references to its assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and meant to be used by API designers (in other words, not taking dependency on implementation details). +To use certain APIs from your project, you must add references to their assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and are meant to be used by API designers (in other words, not taking a dependency on implementation details). -Reference assemblies for .NET Framework standard library are distributed with Targeting Packs. You can obtain them by downloading a standalone isntaller or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core standard library are managed as NuGet packages. For example, [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in .NET Core guide. +Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install the SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. -When you add reference to .NET Framework standard library assemblies in Visual Studio using **Add reference** dialog, you don't have to specify assembly files manually; you select an assembly from the list and Visual Studio automatically finds a reference assembly file corresponding to the target framework version selected in your project. When you add reference to these assemblies in the command line using `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or in Roslyn API using method, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in `%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework directory`. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under `%ProgramFiles%\dotnet\sdk\` on Windows, `/usr/share/dotnet/sdk/` on Linux, or `/usr/local/share/dotnet/sdk` on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locating reference assembly files for the particular target platform. +When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework* directory. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under *%ProgramFiles%\dotnet\sdk\* on Windows, */usr/share/dotnet/sdk/* on Linux, or */usr/local/share/dotnet/sdk* on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate reference assembly files for a particular target platform. -Reference assemblies cannot be loaded for execution, trying to do so results in . However, they still can be loaded into the reflection-only context (using +Because they contain no implementation, reference assemblies cannot be loaded for execution; trying to do so results in a . However, they still can be loaded into the reflection-only context (using the ) method, if you need to examine their contents. ## Generating reference assemblies -Generating reference assemblies for your libraries can be useful when your library consumers often need to build their programs against many different versions of the library (that is, when you need to implement a feature similar to .NET Framework Targeting Packs mentioned above for your own project). Distributing implementation assemblies for all these versions might be impractical due to their large size. Reference assemblies are smaller in size, so distributing them as a part of your library's SDK reduces the download size and saves the disk space. +Generating reference assemblies for your libraries can be useful when your library consumers often need to build their programs against many different versions of the library (that is, when you need to implement a feature similar to .NET Framework Targeting Packs mentioned above for your own project). Distributing implementation assemblies for all these versions might be impractical due to their large size. Reference assemblies are smaller in size, so distributing them as a part of your library's SDK reduces download size and saves disk space. IDEs and build tools also can take advantage of reference assemblies to reduce the build time in case of a large solution consisting of multiple class libraries. Reference assembly doesn't change when programmer changes private implementation details of a class library without affecting its public API, so projects that take dependency on it via the reference assembly don't have to be rebuilt on each of these changes. You can generate reference assemblies: -- In MSBuild project by using `ProduceReferenceAssembly` [project property](/visualstudio/msbuild/common-msbuild-project-properties) +- In an MSBuild project, by using the [`ProduceReferenceAssembly` project property](/visualstudio/msbuild/common-msbuild-project-properties). - When compiling program from command line, by specifiying `-refonly` ([in C#](../../csharp/language-reference/compiler-options/refonly-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([in C#](../../csharp/language-reference/compiler-options/refout-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options -- When using Roslyn API, by setting to `true` and to `false` in an object passed to method. +- When using the Roslyn API, by setting to `true` and to `false` in an object passed to the method. -If you want to distribute reference assemblies with NuGet packages, you must include them in "ref\\" subdirectory under the package directory, instead of "lib\\" subdirectory used for implementation assemblies. +If you want to distribute reference assemblies with NuGet packages, you must include them in the *ref\\* subdirectory under the package directory instead of in the *lib\\* subdirectory used for implementation assemblies. ## Reference assemblies structure Technically, reference assemblies are metadata-only assemblies with certain types of private members excluded. -*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). +*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 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 they will receive a typeload error from the runtime. +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, 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](xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute) 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) +- Private function-members (methods, properties, and events) are removed in cases where their removal doesn't observably impact compilation. If there are no [InternalsVisibleTo](xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute) attributes, internal function members are also removed. +- But all types, including private and nested types. +- All attributes, even internal ones. +- All virtual methods. +- Explicit interface implementations are kept. +- Explicitly implemented properties and events, because their accessors are virtual (and are therefore kept). +- All fields of a struct are kept. Exact reference assembly structure details depend on the compiler version. Newer versions may choose to exclude more metadata if it is determined as not affecting the public API surface. > [!NOTE] -> Information in this section is applicable only to reference assemblies generated by Roslyn compilers starting from C# version 7.1 or Visual Basic version 15.3. Reference assemblies for .NET Framework versions released before that time can have different structure in some details. For example, they might have totally empty method bodies instead of the mentioned single `throw null` body. But the general principle still applies: they don't have usable method implementations and contain metadata only for members which have observable impact from public API perspective. +> Information in this section is applicable only to reference assemblies generated by Roslyn compilers starting from C# version 7.1 or Visual Basic version 15.3. The structure of reference assemblies for .NET Framework versions released before that time can differ in some details. For example, they might have totally empty method bodies instead of the `throw null` body. But the general principle still applies: they don't have usable method implementations and contain metadata only for members that have an observable impact from a public API perspective. ## See also From 0c14a6ed2672d85c0caf86407734831086e25534 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Fri, 13 Sep 2019 13:27:51 +0500 Subject: [PATCH 07/20] address part of review feedback --- .../standard/assembly/reference-assemblies.md | 25 ++++++++++--------- docs/standard/assembly/toc.yml | 2 ++ 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 52d1a827fbfbe..2d567c9343dda 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -29,7 +29,7 @@ Because they contain no implementation, reference assemblies cannot be loaded fo Generating reference assemblies for your libraries can be useful when your library consumers often need to build their programs against many different versions of the library (that is, when you need to implement a feature similar to .NET Framework Targeting Packs mentioned above for your own project). Distributing implementation assemblies for all these versions might be impractical due to their large size. Reference assemblies are smaller in size, so distributing them as a part of your library's SDK reduces download size and saves disk space. -IDEs and build tools also can take advantage of reference assemblies to reduce the build time in case of a large solution consisting of multiple class libraries. Reference assembly doesn't change when programmer changes private implementation details of a class library without affecting its public API, so projects that take dependency on it via the reference assembly don't have to be rebuilt on each of these changes. +IDEs and build tools also can take advantage of reference assemblies to reduce build times in case of large solutions consisting of multiple class libraries. Reference assembly doesn't change when programmer changes private implementation details of a class library without affecting its public API, so projects that take dependency on it via the reference assembly don't have to be rebuilt on each of these changes. You can generate reference assemblies: @@ -41,22 +41,23 @@ If you want to distribute reference assemblies with NuGet packages, you must inc ## Reference assemblies structure -Technically, reference assemblies are metadata-only assemblies with certain types of private members excluded. - -*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 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, they will receive a typeload error from the runtime. +Reference assemblies is an expansion of the related concept, *metadata-only assemblies*. 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 can 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](xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute) attributes, internal function members are also removed. -- But all types, including private and nested types. + +The metadata in reference assemblies continues to retain information about the following: + +- All types, including private and nested types. - All attributes, even internal ones. - All virtual methods. -- Explicit interface implementations are kept. -- Explicitly implemented properties and events, because their accessors are virtual (and are therefore kept). -- All fields of a struct are kept. +- Explicit interface implementations. +- Explicitly implemented properties and events, because their accessors are virtual. +- All fields of structures. + +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). Exact reference assembly structure details depend on the compiler version. Newer versions may choose to exclude more metadata if it is determined as not affecting the public API surface. @@ -65,7 +66,7 @@ Exact reference assembly structure details depend on the compiler version. Newer ## See also -- [Assemblies in the Common Language Runtime](/dotnet/framework/app-domains/assemblies-in-the-common-language-runtime) +- [Assemblies in .NET](index.md) +- [Program with assemblies](program.md) - [Framework targeting overview](/visualstudio/ide/visual-studio-multi-targeting-overview) - [How to: Add or remove references by using the Reference Manager](/visualstudio/ide/how-to-add-or-remove-references-by-using-the-reference-manager) -- [Creating Assemblies](/dotnet/framework/app-domains/create-assemblies) diff --git a/docs/standard/assembly/toc.yml b/docs/standard/assembly/toc.yml index ade609df25332..cf9c6043ba872 100644 --- a/docs/standard/assembly/toc.yml +++ b/docs/standard/assembly/toc.yml @@ -66,3 +66,5 @@ href: load-unload.md - name: "Walkthrough: Embed types from managed assemblies in Visual Studio" href: embed-types-visual-studio.md + + \ No newline at end of file From 4319cfe77bfef4750a5b6b9d65044a5e7c34078d Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Fri, 13 Sep 2019 13:31:12 +0500 Subject: [PATCH 08/20] escape backslashes --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 2d567c9343dda..76856890294c2 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -20,7 +20,7 @@ To use certain APIs from your project, you must add references to their assembli Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install the SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. -When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework* directory. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under *%ProgramFiles%\dotnet\sdk\* on Windows, */usr/share/dotnet/sdk/* on Linux, or */usr/local/share/dotnet/sdk* on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate reference assembly files for a particular target platform. +When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under *%ProgramFiles%\\dotnet\\sdk\\* on Windows, */usr/share/dotnet/sdk/* on Linux, or */usr/local/share/dotnet/sdk* on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate reference assembly files for a particular target platform. Because they contain no implementation, reference assemblies cannot be loaded for execution; trying to do so results in a . However, they still can be loaded into the reflection-only context (using the ) method, if you need to examine their contents. From c5ed5f6d2dc75d86f4cfafdda0050cea70fe9694 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Fri, 13 Sep 2019 15:11:23 +0500 Subject: [PATCH 09/20] address more feedback --- docs/standard/assembly/reference-assemblies.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 76856890294c2..05f63f2dead92 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -10,10 +10,12 @@ ms.technology: dotnet-standard *Reference assemblies* are a special type of assembly that contain only the minimum amount of metadata required to represent the library's public API surface. They include declarations for all members that are significant when referencing an assembly in build tools (hence the name), but exclude all member implementations as well as declarations of private members that have no observable impact on their API contract. In contrast, regular assemblies are called *implementation assemblies*. -Reference assemblies cannot be loaded for execution, but they can be passed as compiler input in the same way as implementation assemblies. Reference assemblies are usually distributed with the Software Development Kit (SDK) of a particular platform or library, a special software component installed only on developer machines. +Reference assemblies cannot be loaded for execution, but they can be passed as compiler input in the same way as implementation assemblies. Reference assemblies are usually distributed with the Software Development Kit (SDK) of a particular platform or library, a special software component installed only on developer machines. Using a reference assembly enables developers to build programs that target a specific library version without having the full implementation assembly for that version. Suppose, you have only the latest version of some library on your machine, but you want to build a program that targets a machine with an earlier version of that library. If you compile directly against the implementation assembly, you might inadvertently use API members that aren't available in the earlier version, and you'll only find this mistake when testing the program on the target machine. If you compile against the reference assembly for the earlier version, you'll immediately get a compile-time error. +Additionally, a reference assembly can represent a contract, that is, a set of APIs that doesn't correspond to the concrete implementation assembly. Such reference assembly, called the *contract assembly*, can be used to target multiple platforms that support the same set of APIs. For example, .NET Standard provides the contract assembly, *netstandard.dll*, that represents the set of common APIs shared between different .NET platforms. The implementations of these APIs are contained in different assemblies on different platforms, such as *mscorlib.dll* on .NET Framework or *System.Private.CoreLib.dll* on .NET Core. A library that targets .NET Standard can run on all platforms that support .NET Standard. + ## Using reference assemblies To use certain APIs from your project, you must add references to their assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and are meant to be used by API designers (in other words, not taking a dependency on implementation details). @@ -29,7 +31,7 @@ Because they contain no implementation, reference assemblies cannot be loaded fo Generating reference assemblies for your libraries can be useful when your library consumers often need to build their programs against many different versions of the library (that is, when you need to implement a feature similar to .NET Framework Targeting Packs mentioned above for your own project). Distributing implementation assemblies for all these versions might be impractical due to their large size. Reference assemblies are smaller in size, so distributing them as a part of your library's SDK reduces download size and saves disk space. -IDEs and build tools also can take advantage of reference assemblies to reduce build times in case of large solutions consisting of multiple class libraries. Reference assembly doesn't change when programmer changes private implementation details of a class library without affecting its public API, so projects that take dependency on it via the reference assembly don't have to be rebuilt on each of these changes. +IDEs and build tools also can take advantage of reference assemblies to reduce build times in case of large solutions consisting of multiple class libraries. Usually, in incremental build scenarios a project is rebuilt when any of its input files are changed, including the assemblies it depends on. The implementation assembly changes whenever the programmer changes the implementation of any member. The reference assembly only changes when its public API is affected. Therefore, using the reference assembly as an input file instead of the implementation assembly allows to skip the build of the dependent project in some cases. You can generate reference assemblies: From 0c3eca1b3f24458c97efa75bb046e7f53e470777 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Fri, 13 Sep 2019 15:39:19 +0500 Subject: [PATCH 10/20] fix grammar --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 05f63f2dead92..42ad83d52e517 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -43,7 +43,7 @@ If you want to distribute reference assemblies with NuGet packages, you must inc ## Reference assemblies structure -Reference assemblies is an expansion of the related concept, *metadata-only assemblies*. 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 can run and pass (thus validating the completeness of the metadata). +Reference assemblies are an expansion of the related concept, *metadata-only assemblies*. 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 can run and pass (thus validating the completeness of the metadata). Reference assemblies further remove metadata (private members) from metadata-only assemblies: From e66138dcca6b016219017588da8eb0d73b1b31e4 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Fri, 13 Sep 2019 15:56:22 +0500 Subject: [PATCH 11/20] remove spaces --- docs/standard/assembly/toc.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/standard/assembly/toc.yml b/docs/standard/assembly/toc.yml index cf9c6043ba872..b85eeff03f022 100644 --- a/docs/standard/assembly/toc.yml +++ b/docs/standard/assembly/toc.yml @@ -67,4 +67,3 @@ - name: "Walkthrough: Embed types from managed assemblies in Visual Studio" href: embed-types-visual-studio.md - \ No newline at end of file From 724bd5a89706d78f064854b22ae2bc412a7fc0f8 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Sat, 14 Sep 2019 23:20:35 +0500 Subject: [PATCH 12/20] remove extra line break --- docs/standard/assembly/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/standard/assembly/index.md b/docs/standard/assembly/index.md index 59abab2a2bd05..5328c34cd4f27 100644 --- a/docs/standard/assembly/index.md +++ b/docs/standard/assembly/index.md @@ -114,4 +114,3 @@ In C#, you can use two versions of the same assembly in a single application. Fo - [How to: Load and unload assemblies](load-unload.md) - [How to: Use and debug assembly unloadability in .NET Core](unloadability.md) - [How to: Determine if a file is an assembly](identify.md) - From b23adc08a2f0e0edde8159d368682bf222e5f8dc Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Sat, 14 Sep 2019 23:21:33 +0500 Subject: [PATCH 13/20] fix TOC order --- docs/standard/assembly/toc.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/standard/assembly/toc.yml b/docs/standard/assembly/toc.yml index b85eeff03f022..10c62217c51d2 100644 --- a/docs/standard/assembly/toc.yml +++ b/docs/standard/assembly/toc.yml @@ -15,10 +15,10 @@ href: side-by-side-execution.md - name: Assembly file format href: file-format.md - - name: Reference assemblies - href: reference-assemblies.md - name: "How to: Use and debug assembly unloadability in .NET Core" href: unloadability.md + - name: Reference assemblies + href: reference-assemblies.md - name: Resolve assembly loads href: resolve-loads.md - name: Program with assemblies From 8594cb90c9d16f67d499ae2388f40943ac8e8427 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Sun, 6 Oct 2019 20:13:08 +0500 Subject: [PATCH 14/20] Update docs/standard/assembly/reference-assemblies.md Co-Authored-By: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 42ad83d52e517..6ddf316d4165a 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -36,7 +36,7 @@ IDEs and build tools also can take advantage of reference assemblies to reduce b You can generate reference assemblies: - In an MSBuild project, by using the [`ProduceReferenceAssembly` project property](/visualstudio/msbuild/common-msbuild-project-properties). -- When compiling program from command line, by specifiying `-refonly` ([in C#](../../csharp/language-reference/compiler-options/refonly-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([in C#](../../csharp/language-reference/compiler-options/refout-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options +- When compiling program from command line, by specifiying `-refonly` ([in C#](../../csharp/language-reference/compiler-options/refonly-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([in C#](../../csharp/language-reference/compiler-options/refout-compiler-option.md), [in Visual Basic](../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options. - When using the Roslyn API, by setting to `true` and to `false` in an object passed to the method. If you want to distribute reference assemblies with NuGet packages, you must include them in the *ref\\* subdirectory under the package directory instead of in the *lib\\* subdirectory used for implementation assemblies. From 79da688e1f718f28b24907538cb7fe63c464653c Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Sun, 6 Oct 2019 20:34:31 +0500 Subject: [PATCH 15/20] Update reference-assemblies.md --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 6ddf316d4165a..6726505f96d9b 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -64,7 +64,7 @@ Reference assemblies include an assembly-level [ReferenceAssembly](xref:System.R Exact reference assembly structure details depend on the compiler version. Newer versions may choose to exclude more metadata if it is determined as not affecting the public API surface. > [!NOTE] -> Information in this section is applicable only to reference assemblies generated by Roslyn compilers starting from C# version 7.1 or Visual Basic version 15.3. The structure of reference assemblies for .NET Framework versions released before that time can differ in some details. For example, they might have totally empty method bodies instead of the `throw null` body. But the general principle still applies: they don't have usable method implementations and contain metadata only for members that have an observable impact from a public API perspective. +> Information in this section is applicable only to reference assemblies generated by Roslyn compilers starting from C# version 7.1 or Visual Basic version 15.3. The structure of reference assemblies for .NET Framework and .NET Core libraries can differ in some details, because they use their own mechanism of generating reference assemblies. For example, they might have totally empty method bodies instead of the `throw null` body. But the general principle still applies: they don't have usable method implementations and contain metadata only for members that have an observable impact from a public API perspective. ## See also From b00c6290d369b8738deb89fba3997d707fbac47c Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Tue, 8 Oct 2019 14:49:47 +0500 Subject: [PATCH 16/20] Address review feedback --- docs/standard/assembly/reference-assemblies.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 6726505f96d9b..288908b80ea9e 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -20,9 +20,9 @@ Additionally, a reference assembly can represent a contract, that is, a set of A To use certain APIs from your project, you must add references to their assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and are meant to be used by API designers (in other words, not taking a dependency on implementation details). -Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package contains reference assemblies that represent common .NET Core APIs. To import these packages, you must first install the SDK for the target platform version you plan to use. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. +Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages?q=Microsoft.NETCore.App.Ref) metapackage contains reference assemblies that represent common .NET Core APIs ([Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage is used instead for versions before 3.0). To target certain platform version, you must install the SDK for that version. .NET Core SDK implicitly references this metapackage, so you don't need to import it manually. NuGet restore operation automatically downloads reference assemblies for the target platform, unless the `EnableTargetingPackDownload` project property is set to `false`. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. -When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. Local cached copies of .NET Core reference assembly files can be found in the NuGetFallbackFolder directory located under *%ProgramFiles%\\dotnet\\sdk\\* on Windows, */usr/share/dotnet/sdk/* on Linux, or */usr/local/share/dotnet/sdk* on MacOS. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate reference assembly files for a particular target platform. +When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. The same applies to adding references directly into MSBuild project using the [Reference](/visualstudio/msbuild/common-msbuild-project-items#reference) project item: you only need to specify the assembly name, not the full file path. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. For .NET Core, you can force publish operation to copy reference assemblies for your target platform into the *publish/refs* subdirectory of your output directory by setting the `PreserveCompilationContext` project property to `true`. Then you can pass these reference assembly files to the compiler. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate their paths. Because they contain no implementation, reference assemblies cannot be loaded for execution; trying to do so results in a . However, they still can be loaded into the reflection-only context (using the ) method, if you need to examine their contents. From ea4db662ff5951e811eb630849691c083d7ea527 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Tue, 8 Oct 2019 14:52:32 +0500 Subject: [PATCH 17/20] Fix link --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 288908b80ea9e..b30a2f7775b49 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -20,7 +20,7 @@ Additionally, a reference assembly can represent a contract, that is, a set of A To use certain APIs from your project, you must add references to their assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and are meant to be used by API designers (in other words, not taking a dependency on implementation details). -Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages?q=Microsoft.NETCore.App.Ref) metapackage contains reference assemblies that represent common .NET Core APIs ([Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage is used instead for versions before 3.0). To target certain platform version, you must install the SDK for that version. .NET Core SDK implicitly references this metapackage, so you don't need to import it manually. NuGet restore operation automatically downloads reference assemblies for the target platform, unless the `EnableTargetingPackDownload` project property is set to `false`. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. +Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages/Microsoft.NETCore.App.Ref) metapackage contains reference assemblies that represent common .NET Core APIs ([Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage is used instead for versions before 3.0). To target certain platform version, you must install the SDK for that version. .NET Core SDK implicitly references this metapackage, so you don't need to import it manually. NuGet restore operation automatically downloads reference assemblies for the target platform, unless the `EnableTargetingPackDownload` project property is set to `false`. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. The same applies to adding references directly into MSBuild project using the [Reference](/visualstudio/msbuild/common-msbuild-project-items#reference) project item: you only need to specify the assembly name, not the full file path. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. For .NET Core, you can force publish operation to copy reference assemblies for your target platform into the *publish/refs* subdirectory of your output directory by setting the `PreserveCompilationContext` project property to `true`. Then you can pass these reference assembly files to the compiler. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate their paths. From e5c378b96bf0564dc46007a7c80f282e5e3f310a Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Tue, 8 Oct 2019 21:43:44 +0500 Subject: [PATCH 18/20] Edit wording --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index b30a2f7775b49..82af39e8dd045 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -20,7 +20,7 @@ Additionally, a reference assembly can represent a contract, that is, a set of A To use certain APIs from your project, you must add references to their assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and are meant to be used by API designers (in other words, not taking a dependency on implementation details). -Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages/Microsoft.NETCore.App.Ref) metapackage contains reference assemblies that represent common .NET Core APIs ([Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage is used instead for versions before 3.0). To target certain platform version, you must install the SDK for that version. .NET Core SDK implicitly references this metapackage, so you don't need to import it manually. NuGet restore operation automatically downloads reference assemblies for the target platform, unless the `EnableTargetingPackDownload` project property is set to `false`. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. +Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages/Microsoft.NETCore.App.Ref) metapackage contains reference assemblies that represent common .NET Core APIs ([Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage is used instead for versions before 3.0). To target certain platform version, you must install the SDK for that version. .NET Core SDK implicitly references the corresponding metapackage, so you don't need to import it manually. NuGet restore operation automatically downloads reference assemblies for the target platform, unless the `EnableTargetingPackDownload` project property is set to `false`. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. The same applies to adding references directly into MSBuild project using the [Reference](/visualstudio/msbuild/common-msbuild-project-items#reference) project item: you only need to specify the assembly name, not the full file path. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. For .NET Core, you can force publish operation to copy reference assemblies for your target platform into the *publish/refs* subdirectory of your output directory by setting the `PreserveCompilationContext` project property to `true`. Then you can pass these reference assembly files to the compiler. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate their paths. From f7c3e4653ffeb1606f5b56100d0d58f6cffe50d7 Mon Sep 17 00:00:00 2001 From: "MSDN.WhiteKnight" <35516665+MSDN-WhiteKnight@users.noreply.github.com> Date: Tue, 15 Oct 2019 14:49:23 +0500 Subject: [PATCH 19/20] Apply dsplaisted's suggestion --- docs/standard/assembly/reference-assemblies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 82af39e8dd045..69ffba422eb54 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -20,7 +20,7 @@ Additionally, a reference assembly can represent a contract, that is, a set of A To use certain APIs from your project, you must add references to their assemblies. You can add references either to implementation assemblies directly or to reference assemblies. We strongly recommend that you use reference assemblies whenever they are available, because doing so ensures that you are using only API members that are supported in the target version and are meant to be used by API designers (in other words, not taking a dependency on implementation details). -Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). Reference assemblies for .NET Core libraries are managed as NuGet packages. For example, the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages/Microsoft.NETCore.App.Ref) metapackage contains reference assemblies that represent common .NET Core APIs ([Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage is used instead for versions before 3.0). To target certain platform version, you must install the SDK for that version. .NET Core SDK implicitly references the corresponding metapackage, so you don't need to import it manually. NuGet restore operation automatically downloads reference assemblies for the target platform, unless the `EnableTargetingPackDownload` project property is set to `false`. For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. +Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). For .NET Core and .NET Standard, reference assemblies are automatically downloaded as necessary (via NuGet) and referenced. For .NET Core 3.0 and higher, the reference assemblies for the core framework are in the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages/Microsoft.NETCore.App.Ref) package (the [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package is used instead for versions before 3.0). For more information, see [Packages, metapackages and frameworks](../../core/packages.md) in the .NET Core Guide. When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. The same applies to adding references directly into MSBuild project using the [Reference](/visualstudio/msbuild/common-msbuild-project-items#reference) project item: you only need to specify the assembly name, not the full file path. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/reference-compiler-option.md) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. For .NET Core, you can force publish operation to copy reference assemblies for your target platform into the *publish/refs* subdirectory of your output directory by setting the `PreserveCompilationContext` project property to `true`. Then you can pass these reference assembly files to the compiler. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate their paths. From 19eb2f58e157b326bd151c1ce36507942b8bca48 Mon Sep 17 00:00:00 2001 From: Andy De George <2672110+Thraka@users.noreply.github.com> Date: Thu, 17 Oct 2019 11:28:52 -0700 Subject: [PATCH 20/20] Update reference-assemblies.md --- docs/standard/assembly/reference-assemblies.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 69ffba422eb54..244b4a71e205a 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -2,7 +2,6 @@ title: "Reference assemblies" description: "Learn about reference assemblies, a special type of assemblies in .NET that contain only the library's public API surface" author: MSDN-WhiteKnight -ms.author: ronpet ms.date: 09/12/2019 ms.technology: dotnet-standard ---