diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 9bcd6286da6d9..44a4cf972610a 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -11226,6 +11226,11 @@ "source_path": "docs/standard/application-essentials.md", "redirect_url": "/dotnet/standard/index" }, + { + "source_path": "docs/standard/analyzers/framework-analyzer.md", + "redirect_url": "/dotnet/framework/code-analyzers", + "redirect_document_id": true + }, { "source_path": "docs/standard/assembly-format.md", "redirect_url": "/dotnet/standard/assembly/file-format", @@ -11455,6 +11460,30 @@ "source_path": "docs/standard/concepts.md", "redirect_url": "/dotnet/standard/" }, + { + "source_path": "docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md", + "redirect_url": "/dotnet/framework/cross-platform/app-resources-for-libraries-that-target-multiple-platforms" + }, + { + "source_path": "docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md", + "redirect_url": "/dotnet/framework/cross-platform/portable-class-library" + }, + { + "source_path": "docs/standard/cross-platform/index.md", + "redirect_url": "/dotnet/framework/cross-platform/index" + }, + { + "source_path": "docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md", + "redirect_url": "/dotnet/framework/cross-platform/passing-a-uri-to-the-windows-runtime" + }, + { + "source_path": "docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md", + "redirect_url": "/dotnet/framework/cross-platform/support-for-windows-store-apps-and-windows-runtime" + }, + { + "source_path": "docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md", + "redirect_url": "/dotnet/framework/cross-platform/using-portable-class-library-with-model-view-view-model" + }, { "source_path": "docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md", "redirect_url": "/dotnet/api/System.IO.WindowsRuntimeStreamExtensions.AsRandomAccessStream" @@ -11471,6 +11500,11 @@ "source_path": "docs/standard/design-guidelines/dispose-pattern.md", "redirect_url": "/dotnet/standard/garbage-collection/implementing-dispose" }, + { + "source_path": "docs/standard/events/how-to-consume-events-in-a-web-forms-application.md", + "redirect_url": "/aspnet/web-forms/overview/how-to-consume-events", + "redirect_document_id": true + }, { "source_path": "docs/standard/exceptions.md", "redirect_url": "/dotnet/standard/exceptions/", diff --git a/docs/csharp/language-reference/keywords/where-generic-type-constraint.md b/docs/csharp/language-reference/keywords/where-generic-type-constraint.md index e89384099787b..1a2eaf26d282c 100644 --- a/docs/csharp/language-reference/keywords/where-generic-type-constraint.md +++ b/docs/csharp/language-reference/keywords/where-generic-type-constraint.md @@ -8,6 +8,7 @@ f1_keywords: - "whereconstraint_CSharpKeyword" - "classconstraint_CSharpKeyword" - "structconstraint_CSharpKeyword" + - "enumconstraint_CSharpKeyword" helpviewer_keywords: - "where (generic type constraint) [C#]" --- diff --git a/docs/framework/code-analyzers.md b/docs/framework/code-analyzers.md new file mode 100644 index 0000000000000..80e0147fa8138 --- /dev/null +++ b/docs/framework/code-analyzers.md @@ -0,0 +1,67 @@ +--- +title: Code analyzers for .NET Framework +titleSuffix: "" +description: Learn how to use the analyzers in the .NET Framework Analyzers package to find and address issues in your code. +author: billwagner +ms.author: wiwagn +ms.date: 10/23/2020 +--- +# Code analysis + +You can use code analyzers to find potential issues in your .NET Framework application code. The analyzers find potential issues and suggest fixes for them. + +Roslyn-based code analyzers run interactively in Visual Studio as you write your code +or as part of a CI build. You should add the analyzers to your project as +early as possible in the development cycle. The sooner you find any potential issues +in your code, the easier they are to fix. The analyzers flag issues in existing code and +warn about new issues as you continue development. + +## Install and configure analyzers + +The .NET Framework Analyzer is delivered in the [Microsoft.NetFramework.Analyzers](https://www.nuget.org/packages/Microsoft.NetFramework.Analyzers/) NuGet package. This package provides analyzers that are specific to .NET Framework APIs, which includes security analyzers. The package is included with the [Microsoft.CodeAnalysis.FxCopAnalyzers package](https://www.nuget.org/packages/Microsoft.CodeAnalysis.FxCopAnalyzers), so if you install that package, there's no need to install the .NET Framework analyzers separately. + +Install the NuGet package on every project where you want the analyzers to run. Only one developer needs to add them +to the project. The analyzer package is a project dependency and will run on every developer's machine once it has the updated solution. + +To install the package, right-click on the project, and select "Manage Dependencies". From the NuGet explorer, search for "Microsoft.NetFramework.Analyzers". Install the latest stable version in all projects in your solution. + +## Use the analyzers + +Once the NuGet package is installed, build your solution. The analyzer will +report any issues it locates in your codebase. The issues are reported as +warnings in the Visual Studio Error List window, as shown in the following image: + +![Issues reported by .NET Framework analyzers.](./media/framework-analyzers-2.png) + +As you write code, you see squiggles underneath any potential issue in your code. +Hover over any issue to get more information and see suggestions +for any possible fix, as shown in the following image: + +![Interactive report of issues found by code analyzers.](./media/framework-analyzers-1.png) + +For more information, see [Code analysis in Visual Studio](/visualstudio/code-quality/roslyn-analyzers-overview). + +## Types of rules + +The analyzers examine the code in your solution and surface warnings with a `CA` prefix. For a list of all possible warnings, see [Code quality rules](../fundamentals/code-analysis/quality-rules/index.md). Only some of these warnings apply to .NET Framework APIS, including: + +- [CA1058: Types should not extend certain base types](../fundamentals/code-analysis/quality-rules/ca1058.md) + +- [CA2153: Do not catch corrupted state exceptions](../fundamentals/code-analysis/quality-rules/ca2153.md) + +- [CA2229: Implement serialization constructors](../fundamentals/code-analysis/quality-rules/ca2229.md) + +- [CA2235: Mark all non-serializable fields](../fundamentals/code-analysis/quality-rules/ca2235.md) + +- [CA2237: Mark ISerializable types with serializable](../fundamentals/code-analysis/quality-rules/ca2237.md) + +- [CA3075: Insecure DTD processing in XML](../fundamentals/code-analysis/quality-rules/ca3075.md) + +- [CA5350: Do not use weak cryptographic algorithms](../fundamentals/code-analysis/quality-rules/ca5350.md) + +- [CA5351 Do not use broken cryptographic algorithms](../fundamentals/code-analysis/quality-rules/ca5351.md) + +## See also + +- [Code analysis in Visual Studio](/visualstudio/code-quality/roslyn-analyzers-overview) +- [Code analysis in the .NET SDK](../fundamentals/code-analysis/overview.md) diff --git a/docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md b/docs/framework/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md similarity index 94% rename from docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md rename to docs/framework/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md index a14434a0e8823..f62ebb1c992ab 100644 --- a/docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md +++ b/docs/framework/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md @@ -1,7 +1,6 @@ --- title: "App Resources for Libraries That Target Multiple Platforms" ms.date: "07/18/2018" -ms.technology: dotnet-standard dev_langs: - "csharp" - "vb" @@ -14,7 +13,7 @@ helpviewer_keywords: ms.assetid: 72c76f0b-7255-4576-9261-3587f949669c --- # App Resources for Libraries That Target Multiple Platforms -You can use the .NET Framework [Portable Class Library](cross-platform-development-with-the-portable-class-library.md) project type to ensure that resources in your class libraries can be accessed from multiple platforms. This project type is available in Visual Studio 2012 and targets the portable subset of the .NET Framework class library. Using a Portable Class Library ensures that your library can be accessed from desktop apps, Silverlight apps, Windows Phone apps, and Windows 8.x Store apps. +You can use the .NET Framework [Portable Class Library](portable-class-library.md) project type to ensure that resources in your class libraries can be accessed from multiple platforms. This project type is available in Visual Studio 2012 and targets the portable subset of the .NET Framework class library. Using a Portable Class Library ensures that your library can be accessed from desktop apps, Silverlight apps, Windows Phone apps, and Windows 8.x Store apps. [!INCLUDE[standard](../../../includes/pcl-to-standard.md)] diff --git a/docs/standard/cross-platform/index.md b/docs/framework/cross-platform/index.md similarity index 87% rename from docs/standard/cross-platform/index.md rename to docs/framework/cross-platform/index.md index 515f6a2c94634..d8bf38f513c9e 100644 --- a/docs/standard/cross-platform/index.md +++ b/docs/framework/cross-platform/index.md @@ -1,7 +1,6 @@ --- title: "Developing for Multiple Platforms with .NET Framework" ms.date: 10/21/2020 -ms.technology: dotnet-standard ms.assetid: b153baaa-130c-4169-860b-e580591de91e --- # Develop for multiple platforms with .NET Framework @@ -19,7 +18,7 @@ To develop for multiple platforms, you can share source code or binaries, and yo |If you want to...|Use...| |-----------------------|------------| |Share source code between Windows Phone 8.1 and Windows 8.1 apps|**Shared projects** (Universal Apps template in Visual Studio 2013, Update 2).

- Currently no Visual Basic support.
- You can separate platform-specific code by using #`if` statements.

For details, see:

- [Start coding](/windows/uwp/get-started/create-uwp-apps)
- [Using Visual Studio to build Universal XAML Apps](https://devblogs.microsoft.com/visualstudio/using-visual-studio-to-build-universal-xaml-apps/) (blog post)
- [Using Visual Studio to Build XAML Converged Apps](https://channel9.msdn.com/Events/Build/2014/3-591) (video)| -|Share binaries between apps that target different platforms|**Portable Class Library projects** for code that is platform-agnostic.

- This approach is typically used for code that implements business logic.
- You can use Visual Basic or C#.
- API support varies by platform.
- Portable Class Library projects that target Windows 8.1 and Windows Phone 8.1 support Windows Runtime APIs and XAML. These features aren't available in older versions of the Portable Class Library.
- If needed, you can abstract out platform-specific code by using interfaces or abstract classes.

For details, see:

- [Portable Class Library](cross-platform-development-with-the-portable-class-library.md)
- [How to Make Portable Class Libraries Work for You](/archive/blogs/dsplaisted/how-to-make-portable-class-libraries-work-for-you) (blog post)
- [Using Portable Class Library with MVVM](using-portable-class-library-with-model-view-view-model.md)
- [App Resources for Libraries That Target Multiple Platforms](app-resources-for-libraries-that-target-multiple-platforms.md)
- [.NET Portability Analyzer](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer) (Visual Studio extension)| +|Share binaries between apps that target different platforms|**Portable Class Library projects** for code that is platform-agnostic.

- This approach is typically used for code that implements business logic.
- You can use Visual Basic or C#.
- API support varies by platform.
- Portable Class Library projects that target Windows 8.1 and Windows Phone 8.1 support Windows Runtime APIs and XAML. These features aren't available in older versions of the Portable Class Library.
- If needed, you can abstract out platform-specific code by using interfaces or abstract classes.

For details, see:

- [Portable Class Library](portable-class-library.md)
- [How to Make Portable Class Libraries Work for You](/archive/blogs/dsplaisted/how-to-make-portable-class-libraries-work-for-you) (blog post)
- [Using Portable Class Library with MVVM](using-portable-class-library-with-model-view-view-model.md)
- [App Resources for Libraries That Target Multiple Platforms](app-resources-for-libraries-that-target-multiple-platforms.md)
- [.NET Portability Analyzer](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer) (Visual Studio extension)| |Share source code between apps for platforms other than Windows 8.1 and Windows Phone 8.1|**Add as link** feature.

- This approach is suitable for app logic that's common to both apps but not portable, for some reason. You can use this feature for C# or Visual Basic code.
For example, Windows Phone 8 and Windows 8 share Windows Runtime APIs, but Portable Class Libraries do not support Windows Runtime for those platforms. You can use `Add as link` to share common Windows Runtime code between a Windows Phone 8 app and a Windows Store app that targets Windows 8.

For details, see:

- [Share code with Add as Link](/previous-versions/windows/apps/jj714082(v=vs.105))
- [How to: Add Existing Items to a Project](/previous-versions/visualstudio/visual-studio-2010/9f4t9t92(v=vs.100))| |Write Windows Store apps using the .NET Framework or call Windows Runtime APIs from .NET Framework code|**Windows Runtime APIs** from your .NET Framework C# or Visual Basic code, and use the .NET Framework to create Windows Store apps. You should be aware of API differences between the two platforms. However, there are classes to help you work with those differences.

For details, see:

- [.NET Framework Support for Windows Store Apps and Windows Runtime](support-for-windows-store-apps-and-windows-runtime.md)
- [Passing a URI to the Windows Runtime](passing-a-uri-to-the-windows-runtime.md)
-
- | |Build .NET Framework apps for non-Microsoft platforms|**Portable Class Library reference assemblies** in the .NET Framework, and a Visual Studio extension or third-party tool such as Xamarin.

For details, see:

- [Portable Class Library now available on all platforms.](https://devblogs.microsoft.com/dotnet/portable-class-library-pcl-now-available-on-all-platforms/) (blog post)
- [Xamarin documentation](/xamarin)| diff --git a/docs/standard/cross-platform/media/add-portable-class-library.png b/docs/framework/cross-platform/media/add-portable-class-library.png similarity index 100% rename from docs/standard/cross-platform/media/add-portable-class-library.png rename to docs/framework/cross-platform/media/add-portable-class-library.png diff --git a/docs/standard/cross-platform/media/pcl-project-properties.png b/docs/framework/cross-platform/media/pcl-project-properties.png similarity index 100% rename from docs/standard/cross-platform/media/pcl-project-properties.png rename to docs/framework/cross-platform/media/pcl-project-properties.png diff --git a/docs/standard/cross-platform/media/using-portable-class-library-with-model-view-view-model/mvvm-share-assemblies-across-platforms.png b/docs/framework/cross-platform/media/using-portable-class-library-with-model-view-view-model/mvvm-share-assemblies-across-platforms.png similarity index 100% rename from docs/standard/cross-platform/media/using-portable-class-library-with-model-view-view-model/mvvm-share-assemblies-across-platforms.png rename to docs/framework/cross-platform/media/using-portable-class-library-with-model-view-view-model/mvvm-share-assemblies-across-platforms.png diff --git a/docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md b/docs/framework/cross-platform/passing-a-uri-to-the-windows-runtime.md similarity index 98% rename from docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md rename to docs/framework/cross-platform/passing-a-uri-to-the-windows-runtime.md index 254fa76c78efb..e01f680aa89df 100644 --- a/docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md +++ b/docs/framework/cross-platform/passing-a-uri-to-the-windows-runtime.md @@ -1,7 +1,6 @@ --- title: "Passing a URI to the Windows Runtime" ms.date: "03/30/2017" -ms.technology: dotnet-standard dev_langs: - "csharp" - "vb" diff --git a/docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md b/docs/framework/cross-platform/portable-class-library.md similarity index 99% rename from docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md rename to docs/framework/cross-platform/portable-class-library.md index aff3311c9e046..9a90158767000 100644 --- a/docs/standard/cross-platform/cross-platform-development-with-the-portable-class-library.md +++ b/docs/framework/cross-platform/portable-class-library.md @@ -2,7 +2,6 @@ title: "Cross-Platform Development with the Portable Class Library" description: Build cross-platform apps and libraries for Microsoft platforms quickly and easily using the Portable Class Library project type in .NET. ms.date: 09/17/2018 -ms.technology: dotnet-standard helpviewer_keywords: - "Portable Class Library [.NET Framework]" - "targeting multiple platforms" diff --git a/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md b/docs/framework/cross-platform/support-for-windows-store-apps-and-windows-runtime.md similarity index 95% rename from docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md rename to docs/framework/cross-platform/support-for-windows-store-apps-and-windows-runtime.md index 982f899a59359..6071a10bd5845 100644 --- a/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md +++ b/docs/framework/cross-platform/support-for-windows-store-apps-and-windows-runtime.md @@ -1,7 +1,6 @@ --- -title: ".NET Framework Support for Windows Store Apps and Windows Runtime" +title: ".NET Framework Support for Microsoft Store Apps and Windows Runtime" ms.date: "03/30/2017" -ms.technology: dotnet-standard helpviewer_keywords: - "Windows Store apps, .NET Framework support for" - "Windows Runtime, .NET Framework support for" @@ -10,7 +9,7 @@ helpviewer_keywords: - ".NET Framework, and Windows Runtime" ms.assetid: 6fa7d044-ae12-4c54-b8ee-50915607a565 --- -# .NET Framework Support for Windows Store Apps and Windows Runtime +# .NET Framework Support for Microsoft Store Apps and Windows Runtime The .NET Framework 4.5 supports a number of software development scenarios with the Windows Runtime. These scenarios fall into three categories: @@ -18,9 +17,9 @@ The .NET Framework 4.5 supports a number of software development scenarios with - Developing class libraries to use in the Windows 8.x Store apps that you create with the .NET Framework. -- Developing Windows Runtime Components, packaged in .WinMD files, which can be used by any programming language that supports the Windows Runtime. For example, see [Creating Windows Runtime Components in C# and Visual Basic](/windows/uwp/winrt-components/creating-windows-runtime-components-in-csharp-and-visual-basic). +- Developing Windows Runtime Components, packaged in .WinMD files, that can be used by any programming language that supports the Windows Runtime. For example, see [Creating Windows Runtime Components in C# and Visual Basic](/windows/uwp/winrt-components/creating-windows-runtime-components-in-csharp-and-visual-basic). -This topic outlines the support that the .NET Framework provides for all three categories, and describes the scenarios for Windows Runtime Components. The first section includes basic information about the relationship between the .NET Framework and the Windows Runtime, and explains some oddities you might encounter in the Help system and the IDE. The [second section](#WindowsRuntimeComponents) discusses scenarios for developing Windows Runtime Components. +This article outlines the support that the .NET Framework provides for all three categories, and describes the scenarios for Windows Runtime Components. The first section includes basic information about the relationship between the .NET Framework and the Windows Runtime, and explains some oddities you might encounter in the Help system and the IDE. The [second section](#WindowsRuntimeComponents) discusses scenarios for developing Windows Runtime Components. ## The Basics diff --git a/docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md b/docs/framework/cross-platform/using-portable-class-library-with-model-view-view-model.md similarity index 94% rename from docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md rename to docs/framework/cross-platform/using-portable-class-library-with-model-view-view-model.md index 27c8e675b0ea0..38d28a106a25f 100644 --- a/docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md +++ b/docs/framework/cross-platform/using-portable-class-library-with-model-view-view-model.md @@ -1,7 +1,6 @@ --- title: "Using Portable Class Library with Model-View-View Model" ms.date: "07/18/2018" -ms.technology: dotnet-standard dev_langs: - "csharp" - "vb" @@ -11,7 +10,7 @@ helpviewer_keywords: ms.assetid: 41a0b9f8-15a2-431a-bc35-e310b2953b03 --- # Using Portable Class Library with Model-View-View Model -You can use the .NET Framework [Portable Class Library](cross-platform-development-with-the-portable-class-library.md) to implement the Model-View-View Model (MVVM) pattern and share assemblies across multiple platforms. +You can use the .NET Framework [Portable Class Library](portable-class-library.md) to implement the Model-View-View Model (MVVM) pattern and share assemblies across multiple platforms. [!INCLUDE[standard](../../../includes/pcl-to-standard.md)] @@ -85,4 +84,4 @@ You can use the .NET Framework [Portable Class Library](cross-platform-developme ## See also -- [Portable Class Library](cross-platform-development-with-the-portable-class-library.md) +- [Portable Class Library](portable-class-library.md) diff --git a/docs/standard/analyzers/media/framework-analyzers-1.png b/docs/framework/media/framework-analyzers-1.png similarity index 100% rename from docs/standard/analyzers/media/framework-analyzers-1.png rename to docs/framework/media/framework-analyzers-1.png diff --git a/docs/standard/analyzers/media/framework-analyzers-2.png b/docs/framework/media/framework-analyzers-2.png similarity index 100% rename from docs/standard/analyzers/media/framework-analyzers-2.png rename to docs/framework/media/framework-analyzers-2.png diff --git a/docs/framework/toc.yml b/docs/framework/toc.yml index 8cfda665609dd..0487c60deb874 100644 --- a/docs/framework/toc.yml +++ b/docs/framework/toc.yml @@ -725,24 +725,20 @@ items: href: misc/using-libraries-from-partially-trusted-code.md - name: Using the Assert Method href: misc/using-the-assert-method.md -- name: Create console apps - href: ../standard/building-console-apps.md -- name: Consume events in a Web Forms app - href: ../standard/events/how-to-consume-events-in-a-web-forms-application.md -- name: .NET Framework code analyzer - href: ../standard/analyzers/framework-analyzer.md +- name: Code analysis + href: code-analyzers.md - name: Develop for multiple platforms items: - name: Overview - href: ../standard/cross-platform/index.md + href: cross-platform/index.md displayName: cross platform - name: Portable Class Library - href: ../standard/cross-platform/cross-platform-development-with-the-portable-class-library.md + href: cross-platform/portable-class-library.md - name: Use Portable Class Library with MVVM - href: ../standard/cross-platform/using-portable-class-library-with-model-view-view-model.md + href: cross-platform/using-portable-class-library-with-model-view-view-model.md - name: App resources for libraries that target multiple platforms - href: ../standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md + href: cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md - name: .NET Framework support for Microsoft Store apps and Windows Runtime - href: ../standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md + href: cross-platform/support-for-windows-store-apps-and-windows-runtime.md - name: Pass a URI to the Windows Runtime - href: ../standard/cross-platform/passing-a-uri-to-the-windows-runtime.md + href: cross-platform/passing-a-uri-to-the-windows-runtime.md diff --git a/docs/framework/wcf/add-service-reference-in-a-portable-subset-project.md b/docs/framework/wcf/add-service-reference-in-a-portable-subset-project.md index b75215f3b88f6..0e1ce9ea15bb1 100644 --- a/docs/framework/wcf/add-service-reference-in-a-portable-subset-project.md +++ b/docs/framework/wcf/add-service-reference-in-a-portable-subset-project.md @@ -41,4 +41,4 @@ Portable subset projects enable .NET assembly programmers to maintain a single s ## See also - [Accessing Services Using a WCF Client](accessing-services-using-a-wcf-client.md) -- [Portable Class Library](../../standard/cross-platform/cross-platform-development-with-the-portable-class-library.md) +- [Portable Class Library](../cross-platform/portable-class-library.md) diff --git a/docs/framework/whats-new/index.md b/docs/framework/whats-new/index.md index 671e502c95b83..e0876a68efc81 100644 --- a/docs/framework/whats-new/index.md +++ b/docs/framework/whats-new/index.md @@ -1850,7 +1850,7 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - You can retarget a Windows Store or Windows Phone Store class library like a Portable Class Library. - For more information about these changes, see [Portable Class Library](../../standard/cross-platform/cross-platform-development-with-the-portable-class-library.md). + For more information about these changes, see [Portable Class Library](../cross-platform/portable-class-library.md). - The .NET Framework content set now includes documentation for .NET Native, which is a precompilation technology for building and deploying Windows apps. .NET Native compiles your apps directly to native code, rather than to intermediate language (IL), for better performance. For details, see [Compiling Apps with .NET Native](../net-native/index.md). @@ -2120,13 +2120,12 @@ Windows 8.x Store apps are designed for specific form factors and leverage the p ### Portable Class Libraries -The Portable Class Library project in Visual Studio 2012 (and later versions) enables you to write and build managed assemblies that work on multiple .NET Framework platforms. Using a Portable Class Library project, you choose the platforms (such as Windows Phone and .NET for Windows 8.x Store apps) to target. The available types and members in your project are automatically restricted to the common types and members across these platforms. For more information, see [Portable Class Library](../../standard/cross-platform/cross-platform-development-with-the-portable-class-library.md). +The Portable Class Library project in Visual Studio 2012 (and later versions) enables you to write and build managed assemblies that work on multiple .NET Framework platforms. Using a Portable Class Library project, you choose the platforms (such as Windows Phone and .NET for Windows 8.x Store apps) to target. The available types and members in your project are automatically restricted to the common types and members across these platforms. For more information, see [Portable Class Library](../cross-platform/portable-class-library.md). ## See also - [The .NET Framework and Out-of-Band Releases](../get-started/the-net-framework-and-out-of-band-releases.md) - [What's new in accessibility in .NET Framework](whats-new-in-accessibility.md) -- [What's New in Visual Studio 2017](/visualstudio/ide/whats-new-visual-studio-2017) - [What's New in Visual Studio 2019](/visualstudio/ide/whats-new-visual-studio-2019) - [ASP.NET](/aspnet) - [What's New for C++ in Visual Studio](/cpp/what-s-new-for-visual-cpp-in-visual-studio) diff --git a/docs/fundamentals/code-analysis/overview.md b/docs/fundamentals/code-analysis/overview.md index 579de442bc20a..bf7b15f18b132 100644 --- a/docs/fundamentals/code-analysis/overview.md +++ b/docs/fundamentals/code-analysis/overview.md @@ -143,7 +143,7 @@ For more information about rule severities, see [Configure rule severity](config ## See also - [Code quality analysis rule reference](quality-rules/index.md) -- [Code style analysis rule reference](/visualstudio/ide/editorconfig-code-style-settings-reference) +- [Code style analysis rule reference](style-rules/index.md) - [Code analysis in Visual Studio](/visualstudio/code-quality/roslyn-analyzers-overview) - [.NET Compiler Platform SDK](../../csharp/roslyn-sdk/index.md) - [Tutorial: Write your first analyzer and code fix](../../csharp/roslyn-sdk/tutorials/how-to-write-csharp-analyzer-code-fix.md) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index aab7b63279ec4..feead8f85ce2c 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -1524,6 +1524,8 @@ items: href: ../standard/attributes/retrieving-information-stored-in-attributes.md - name: Choose between anonymous and tuple types href: ../standard/base-types/choosing-between-anonymous-and-tuple.md + - name: Console app concepts + href: ../standard/building-console-apps.md - name: Dependency injection items: - name: Overview diff --git a/docs/standard/analyzers/framework-analyzer.md b/docs/standard/analyzers/framework-analyzer.md deleted file mode 100644 index 3bc5f5cd5e4ed..0000000000000 --- a/docs/standard/analyzers/framework-analyzer.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: .NET Framework Analyzers - .NET -description: Learn how to use the .NET Framework Analyzers in the .NET Framework Analyzers package to find and address security risks -author: billwagner -ms.author: wiwagn -ms.date: 01/25/2018 -ms.technology: dotnet-standard ---- -# The .NET Framework Analyzer - -You can use the .NET Framework Analyzer to find potential issues in your .NET Framework-based application code. This analyzer finds potential issues and suggests -fixes to them. - -The analyzer runs interactively in Visual Studio as you write your code -or as part of a CI build. You should add the analyzer to your project as -early as possible in your development. The sooner you find any potential issues -in your code, the easier they are to fix. However, you can add it at any time -in the development cycle. It finds any issues with the existing code and -warns about new issues as you keep developing. - -## Installing and configuring the .NET Framework Analyzer - -The .NET Framework Analyzers must be installed as a NuGet package on every -project where you want them to run. Only one developer needs to add them -to the project. The analyzer package is a project dependency and will run -on every developer's machine once it has the updated solution. - -The .NET Framework Analyzer is delivered in the [Microsoft.NetFramework.Analyzers](https://www.nuget.org/packages/Microsoft.NetFramework.Analyzers/) -NuGet package. This package provides only the analyzers specific to the .NET Framework, which -includes security analyzers. In most cases, you'll want -the [Microsoft.CodeAnalysis.FxCopAnalyzers](https://www.nuget.org/packages/Microsoft.CodeAnalysis.FxCopAnalyzers) NuGet package. -The FxCopAnalyzers aggregate package contains all the framework analyzers included in the -Framework.Analyzers package as well as the following analyzers: - -- [Microsoft.CodeQuality.Analyzers](https://www.nuget.org/packages/Microsoft.CodeQuality.Analyzers): Provides general guidance and guidance for .NET Standard APIs -- [Microsoft.NetCore.Analyzers](https://www.nuget.org/packages/Microsoft.NetCore.Analyzers): Provides analyzers specific to .NET Core APIs. -- [Text.Analyzers](https://www.nuget.org/packages/Text.Analyzers): Provides guidance for text included as code, including comments. - -To install it, right-click on the project, and select "Manage Dependencies". -From the NuGet explorer, search for "NetFramework Analyzer", or if you prefer, -"Fx Cop Analyzer". Install the latest stable version in all projects in your -solution. - -## Using the .NET Framework Analyzer - -Once the NuGet package is installed, build your solution. The analyzer will -report any issues it locates in your codebase. The issues are reported as -warnings in the Visual Studio Error List window, as shown in the following image: - -![issues reported by the framework analyzer](./media/framework-analyzers-2.png) - -As you write code, you see squiggles underneath any potential issue in your code. -Hover over any issue and you see details about the issue, and suggestions -for any possible fix, as shown in the following image: - -![interactive report of issues found by the framework analyzer](./media/framework-analyzers-1.png) - -The analyzers examine -the code in your solution and provide you with a list of -warnings for any of these issues: - -### CA1058: Types should not extend certain base types - -There are a small number of types in the .NET Framework that you should not derived from directly. - -**Category:** Design - -**Severity:** Warning - -Additional information: [CA:1058: Types should not extend certain base types](/visualstudio/code-quality/ca1058-types-should-not-extend-certain-base-types) - -### CA2153: Do not catch corrupted state exceptions - -Catching corrupted state exceptions could mask errors (such as access violations), resulting in an inconsistent state of execution or making it easier for attackers to compromise a system. Instead, catch and handle a more specific set of exception type(s) or re-throw the exception - -**Category:** Security - -**Severity:** Warning - -Additional information: [## CA2153: Do not catch corrupted state exceptions](/visualstudio/code-quality/ca2153-avoid-handling-corrupted-state-exceptions) - -### CA2229: Implement serialization constructors - -The analyzer generates this warning when you create a type that implements the interface but does not define the required serialization constructor. To fix a violation of this rule, implement the serialization constructor. For a sealed class, make the constructor private; otherwise, make it protected. The serialization constructor has the following signature: - -```csharp -public class MyItemType -{ - // The special constructor is used to deserialize values. - public MyItemType(SerializationInfo info, StreamingContext context) - { - // implementation removed. - } -} -``` - -**Category:** Usage - -**Severity:** Warning - -Additional information: [CA2229: Implement serialization constructors](/visualstudio/code-quality/ca2229-implement-serialization-constructors) - -### CA2235: Mark all non-serializable fields - -An instance field of a type that is not serializable is declared in a type that is serializable. You must explicitly mark that field with the to fix this warning. - -**Category:** Usage - -**Severity:** Warning - -Additional information: [CA2235: Mark all non-serializable fields](/visualstudio/code-quality/ca2235-mark-all-non-serializable-fields) - -### CA2237: Mark ISerializable types with serializable - -To be recognized by the common language runtime as serializable, types must be marked by using the attribute even when the type uses a custom serialization routine by implementing the interface. - -**Category:** Usage - -**Severity:** Warning - -Additional information: [CA2237: Mark ISerializable types with serializable](/visualstudio/code-quality/ca2237-mark-iserializable-types-with-serializableattribute) - -### CA3075: Insecure DTD processing in XML - -If you use insecure instances or reference external entity sources, the parser may accept untrusted input and disclose sensitive information to attackers. - -**Category:** Security - -**Severity:** Warning - -Additional information: [A3075: Insecure DTD processing in XML](/visualstudio/code-quality/ca2237-mark-iserializable-types-with-serializableattribute) - -### CA5350: Do not use weak cryptographic algorithms - -Cryptographic algorithms degrade over time as attacks become more advanced. Depending on the type and application of this cryptographic algorithm, further degradation of its cryptographic strength may allow attackers to read enciphered messages, tamper with enciphered messages, forge digital signatures, tamper with hashed content, or otherwise compromise any cryptosystem based on this algorithm. For encryption, use an AES algorithm (AES-256, AES-192 and AES-128 are acceptable) with a key length greater than or equal to 128 bits. For hashing, use a hashing function in the SHA-2 family, such as SHA-2 512, SHA-2 384, or SHA-2 256. - -**Category:** Security - -**Severity:** Warning - -Additional information: [CA5350: Do not use weak cryptographic algorithms](/visualstudio/code-quality/ca5350-do-not-use-weak-cryptographic-algorithms) - -### CA5351: Do not use broken cryptographic algorithms - -An attack making it computationally feasible to break this algorithm exists. This allows attackers to break the cryptographic guarantees it is designed to provide. Depending on the type and application of this cryptographic algorithm, this may allow attackers to read enciphered messages, tamper with enciphered messages, forge digital signatures, tamper with hashed content, or otherwise compromise any cryptosystem based on this algorithm. For encryption, use an AES algorithm (AES-256, AES-192 and AES-128 are acceptable) with a key length greater than or equal to 128 bits. For hashing, use a hashing function in the SHA-2 family, such as SHA512, SHA384, or SHA256. For digital signatures, use RSA with a key length greater than or equal to 2048-bits, or ECDSA with a key length greater than or equal to 256 bits. - -**Category:** Security - -**Severity:** Warning - -Additional Information: [CA5351: Do not use broken cryptographic algorithms](/visualstudio/code-quality/ca5351) diff --git a/docs/standard/assembly/find-fully-qualified-name.md b/docs/standard/assembly/find-fully-qualified-name.md index b3436b856513b..b2a74cc5fa75b 100644 --- a/docs/standard/assembly/find-fully-qualified-name.md +++ b/docs/standard/assembly/find-fully-qualified-name.md @@ -1,11 +1,11 @@ --- title: "How to: Find an assembly's fully qualified name" -description: This article shows you how to get the fully qualified name of a .NET Framework assembly or .NET Core assembly. +description: This article shows you how to get the fully qualified name of a .NET assembly. ms.date: "08/20/2019" helpviewer_keywords: - - "names [.NET Framework], fully qualified type names" - - "names [.NET Framework], assemblies" - - "assemblies [.NET Framework], names" + - "names [.NET], fully qualified type names" + - "names [.NET], assemblies" + - "assemblies [.NET], names" ms.assetid: 009dae23-e1f6-4a64-9a9a-32e4c34802b0 dev_langs: - "csharp" diff --git a/docs/standard/assembly/location.md b/docs/standard/assembly/location.md index 9b40af206f02c..b67a437363651 100644 --- a/docs/standard/assembly/location.md +++ b/docs/standard/assembly/location.md @@ -4,10 +4,11 @@ description: The location of a .NET assembly determines how the CLR finds it and ms.date: "08/20/2019" helpviewer_keywords: - "locating assemblies" - - "assemblies [.NET Framework], location" + - "assemblies [.NET], location" ms.assetid: 9f1f41a7-2954-49d3-a2c0-62b6ef4d40ab --- # Assembly location + An assembly's location determines whether the common language runtime can locate it when referenced, and can also determine whether the assembly can be shared with other assemblies. You can deploy an assembly in the following locations: - The application's directory or subdirectories. diff --git a/docs/standard/assembly/manifest.md b/docs/standard/assembly/manifest.md index c511b34c32c53..9727fd47d8250 100644 --- a/docs/standard/assembly/manifest.md +++ b/docs/standard/assembly/manifest.md @@ -7,10 +7,11 @@ helpviewer_keywords: - "dynamic assemblies, assembly manifest" - "metadata, assembly manifest" - "culture, assembly manifest" - - "assemblies [.NET Framework], metadata" + - "assemblies [.NET], metadata" ms.assetid: 8e40fab9-549d-4731-aec2-ffa47a382de0 --- # Assembly manifest + Every assembly, whether static or dynamic, contains a collection of data that describes how the elements in the assembly relate to each other. The assembly manifest contains this assembly metadata. An assembly manifest contains all the metadata needed to specify the assembly's version requirements and security identity, and all metadata needed to define the scope of the assembly and resolve references to resources and classes. The assembly manifest can be stored in either a PE file (an *.exe* or *.dll*) with Microsoft intermediate language (MSIL) code or in a standalone PE file that contains only assembly manifest information. The following illustration shows the different ways the manifest can be stored. diff --git a/docs/standard/assembly/names.md b/docs/standard/assembly/names.md index 888fd2cd7e68b..65e56eaff1725 100644 --- a/docs/standard/assembly/names.md +++ b/docs/standard/assembly/names.md @@ -3,33 +3,34 @@ title: "Assembly names" description: Learn about .NET assembly names and their impact on assembly scope and use by an application, and learn about the FullName property. ms.date: "08/19/2019" helpviewer_keywords: - - "names [.NET Framework], assemblies" - - "assemblies [.NET Framework], names" + - "names [.NET], assemblies" + - "assemblies [.NET], names" ms.assetid: 8f8c2c90-f15d-400e-87e7-a757e4f04d0e --- # Assembly names -An assembly's name is stored in metadata and has a significant impact on the assembly's scope and use by an application. A strong-named assembly has a fully qualified name that includes the assembly's name, culture, public key, and version number. This is frequently referred to as the display name, and for loaded assemblies can be obtained by using the property. - The runtime uses this information to locate the assembly and differentiate it from other assemblies with the same name. For example, a strong-named assembly called `myTypes` could have the following fully qualified name: +An assembly's name is stored in metadata and has a significant impact on the assembly's scope and use by an application. A strong-named assembly has a fully qualified name that includes the assembly's name, culture, public key, version number, and, optionally, processor architecture. Use the property to obtain the fully qualified name, frequently referred to as the display name, for loaded assemblies. + +The runtime uses the name information to locate the assembly and differentiate it from other assemblies with the same name. For example, a strong-named assembly called `myTypes` could have the following fully qualified name: ``` myTypes, Version=1.0.1234.0, Culture=en-US, PublicKeyToken=b77a5c561934e089c, ProcessorArchitecture=msil ``` -> [!NOTE] -> Processor architecture is added to the assembly identity in the .NET Framework version 2.0, to allow processor-specific versions of assemblies. You can create versions of an assembly whose identity differs only by processor architecture, for example 32-bit and 64-bit processor-specific versions. Processor architecture is not required for strong names. For more information, see . +In this example, the fully qualified name indicates that the `myTypes` assembly has a strong name with a public key token, has the culture value for United States English, and has a version number of 1.0.1234.0. Its processor architecture is `msil`, which means that it will be just-in-time (JIT)-compiled to 32-bit code or 64-bit code depending on the operating system and processor. - In this example, the fully qualified name indicates that the `myTypes` assembly has a strong name with a public key token, has the culture value for US English, and has a version number of 1.0.1234.0. Its processor architecture is "msil", which means that it will be just-in-time (JIT)-compiled to 32-bit code or 64-bit code depending on the operating system and processor. +> [!TIP] +> The `ProcessorArchitecture` information allows processor-specific versions of assemblies. You can create versions of an assembly whose identity differs only by processor architecture, for example 32-bit and 64-bit processor-specific versions. Processor architecture is not required for strong names. For more information, see . - Code that requests types in an assembly must use a fully qualified assembly name. This is called fully qualified binding. Partial binding, which specifies only an assembly name, is not permitted when referencing assemblies in the .NET Framework. + Code that requests types in an assembly must use a fully qualified assembly name. This is called fully qualified binding. Partial binding, which specifies only an assembly name, is not permitted when referencing assemblies in .NET Framework. - All assembly references to assemblies that make up the .NET Framework must also contain the fully qualified name of the assembly. For example, a reference to the System.Data .NET Framework assembly for version 1.0 would include: + All assembly references to assemblies that make up .NET Framework must also contain the fully qualified name of the assembly. For example, a reference to the System.Data .NET Framework assembly for version 1.0 would include: ``` System.data, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 ``` - Note that the version corresponds to the version number of all .NET Framework assemblies that shipped with .NET Framework version 1.0. For .NET Framework assemblies, the culture value is always neutral, and the public key is the same as shown in the above example. +The version corresponds to the version number of all .NET Framework assemblies that shipped with .NET Framework version 1.0. For .NET Framework assemblies, the culture value is always neutral, and the public key is the same as shown in the above example. For example, to add an assembly reference in a configuration file to set up a trace listener, you would include the fully qualified name of the system .NET Framework assembly: @@ -48,7 +49,7 @@ System.data, version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e08 To avoid this problem, make sure the assemblies that make up your application do not have the same assembly name or place assemblies with the same name in different directories. > [!NOTE] -> In the .NET Framework, if you put a strong-named assembly in the global assembly cache, the assembly's file name must match the assembly name, not including the file name extension, such as *.exe* or *.dll*. For example, if the file name of an assembly is *myAssembly.dll*, the assembly name must be `myAssembly`. Private assemblies deployed only in the root application directory can have an assembly name that is different from the file name. +> In .NET Framework, if you put a strong-named assembly in the global assembly cache, the assembly's file name must match the assembly name, not including the file name extension, such as *.exe* or *.dll*. For example, if the file name of an assembly is *myAssembly.dll*, the assembly name must be `myAssembly`. Private assemblies deployed only in the root application directory can have an assembly name that is different from the file name. ## See also diff --git a/docs/standard/assembly/reference-strong-named.md b/docs/standard/assembly/reference-strong-named.md index ec56766cc9158..e8229c7600f27 100644 --- a/docs/standard/assembly/reference-strong-named.md +++ b/docs/standard/assembly/reference-strong-named.md @@ -5,7 +5,7 @@ ms.date: "08/20/2019" helpviewer_keywords: - "strong-named assemblies, compile-time references" - "compile-time assembly referencing" - - "assemblies [.NET Framework], strong-named" + - "assemblies [.NET], strong-named" - "assembly binding, strong-named" ms.assetid: 4c6a406a-b5eb-44fa-b4ed-4e95bb95a813 dev_langs: diff --git a/docs/standard/assembly/resolve-loads.md b/docs/standard/assembly/resolve-loads.md index c352cfd0c3d5f..f1cac610a56eb 100644 --- a/docs/standard/assembly/resolve-loads.md +++ b/docs/standard/assembly/resolve-loads.md @@ -3,10 +3,10 @@ title: "Resolve assembly loads" description: This article describes the .NET AppDomain.AssemblyResolve event. Use this event for applications that require control over assembly loading. ms.date: "08/20/2019" helpviewer_keywords: - - "assemblies [.NET Framework], resolving loads" + - "assemblies [.NET], resolving loads" - "application domains, loading assemblies" - "resolving assembly loads" - - "assemblies [.NET Framework], loading" + - "assemblies [.NET], loading" - "application domains, resolving assembly loads" ms.assetid: 5099e549-f4fd-49fb-a290-549edd456c6a dev_langs: @@ -15,6 +15,7 @@ dev_langs: - "cpp" --- # Resolve assembly loads + .NET provides the event for applications that require greater control over assembly loading. By handling this event, your application can load an assembly into the load context from outside the normal probing paths, select which of several assembly versions to load, emit a dynamic assembly and return it, and so on. This topic provides guidance for handling the event. > [!NOTE] diff --git a/docs/standard/assembly/security-considerations.md b/docs/standard/assembly/security-considerations.md index 83ccbfa52f191..a1255ce04246d 100644 --- a/docs/standard/assembly/security-considerations.md +++ b/docs/standard/assembly/security-considerations.md @@ -3,21 +3,22 @@ title: "Assembly security considerations" description: When you build a .NET assembly, you can specify permissions the assembly requires to run. This article discusses strong-named assemblies and signing tools. ms.date: "08/20/2019" helpviewer_keywords: - - "assemblies [.NET Framework], security" + - "assemblies [.NET], security" - "signcodes" - - "names [.NET Framework], assemblies" + - "names [.NET], assemblies" - "strong-named assemblies, security considerations" - "signing assemblies" - - "assemblies [.NET Framework], signing" + - "assemblies [.NET], signing" - "granting permissions, assemblies" - - "assemblies [.NET Framework], strong-named" - - "names [.NET Framework], strong names" - - "permissions [.NET Framework], assemblies" - - "security [.NET Framework], assemblies" + - "assemblies [.NET], strong-named" + - "names [.NET], strong names" + - "permissions [.NET], assemblies" + - "security [.NET], assemblies" - "integrity with assemblies" ms.assetid: 1b5439c1-f3d5-4529-bd69-01814703d067 --- # Assembly security considerations + When you build an assembly, you can specify a set of permissions that the assembly requires to run. Whether certain permissions are granted or not granted to an assembly is based on evidence. There are two distinct ways evidence is used: diff --git a/docs/standard/assembly/set-attributes.md b/docs/standard/assembly/set-attributes.md index dd2ed716a0962..2d81b7610c0b1 100644 --- a/docs/standard/assembly/set-attributes.md +++ b/docs/standard/assembly/set-attributes.md @@ -3,7 +3,7 @@ title: "Set assembly attributes" description: You can set assembly attributes for a .NET assembly, including assembly identity, informational, assembly manifest, and strong name attributes. ms.date: "08/20/2019" helpviewer_keywords: - - "assemblies [.NET Framework], attributes" + - "assemblies [.NET], attributes" - "assembly binding, attributes" - "assembly manifest, attributes" ms.assetid: 36a98a81-b5b5-4c19-912a-11f91eff7f4e diff --git a/docs/standard/assembly/side-by-side-execution.md b/docs/standard/assembly/side-by-side-execution.md index 9dc46deb66c7d..89f50b5727d5c 100644 --- a/docs/standard/assembly/side-by-side-execution.md +++ b/docs/standard/assembly/side-by-side-execution.md @@ -3,8 +3,8 @@ title: "Assemblies and side-by-side execution" description: Learn about side-by-side execution, which is the ability to store and run multiple versions of an application or component on the same computer. ms.date: "08/20/2019" helpviewer_keywords: - - "side-by-side execution [.NET Framework]" - - "assemblies [.NET Framework], side-by-side execution" + - "side-by-side execution [.NET]" + - "assemblies [.NET], side-by-side execution" ms.assetid: e42036ee-7590-47d1-b884-cc856e39bd5d --- # Assemblies and side-by-side execution diff --git a/docs/standard/assembly/sign-strong-name.md b/docs/standard/assembly/sign-strong-name.md index bee82a8f68b83..038136ef07744 100644 --- a/docs/standard/assembly/sign-strong-name.md +++ b/docs/standard/assembly/sign-strong-name.md @@ -5,8 +5,8 @@ ms.date: "08/20/2019" helpviewer_keywords: - "strong-named assemblies, signing with strong names" - "signing assemblies" - - "assemblies [.NET Framework], signing" - - "assemblies [.NET Framework], strong-named" + - "assemblies [.NET], signing" + - "assemblies [.NET], strong-named" ms.assetid: 2c30799a-a826-46b4-a25d-c584027a6c67 dev_langs: - "csharp" diff --git a/docs/standard/assembly/type-forwarding.md b/docs/standard/assembly/type-forwarding.md index 5c2367833ddd5..c63e006e77357 100644 --- a/docs/standard/assembly/type-forwarding.md +++ b/docs/standard/assembly/type-forwarding.md @@ -3,7 +3,7 @@ title: "Type forwarding in the common language runtime" description: Type forwarding allows you to move a type to another .NET assembly without having to recompile applications that use the original assembly. ms.date: "08/20/2019" helpviewer_keywords: - - "assemblies [.NET Framework], type forwarding" + - "assemblies [.NET], type forwarding" - "type forwarding" ms.assetid: 51f8ffa3-c253-4201-a3d3-c4fad85ae097 dev_langs: @@ -11,16 +11,15 @@ dev_langs: - "cpp" --- # Type forwarding in the common language runtime + Type forwarding allows you to move a type to another assembly without having to recompile applications that use the original assembly. For example, suppose an application uses the `Example` class in an assembly named *Utility.dll*. The developers of *Utility.dll* might decide to refactor the assembly, and in the process they might move the `Example` class to another assembly. If the old version of *Utility.dll* is replaced by the new version of *Utility.dll* and its companion assembly, the application that uses the `Example` class fails because it cannot locate the `Example` class in the new version of *Utility.dll*. - The developers of *Utility.dll* can avoid this by forwarding requests for the `Example` class, using the attribute. If the attribute has been applied to the new version of *Utility.dll*, requests for the `Example` class are forwarded to the assembly that now contains the class. The existing application continues to function normally, without recompilation. - -> [!NOTE] -> In the .NET Framework version 2.0, you cannot forward types from assemblies written in Visual Basic. However, an application written in Visual Basic can consume forwarded types. That is, if the application uses an assembly coded in C# or C++, and a type from that assembly is forwarded to another assembly, the Visual Basic application can use the forwarded type. - -## Forward types + The developers of *Utility.dll* can avoid this by forwarding requests for the `Example` class, using the attribute. If the attribute has been applied to the new version of *Utility.dll*, requests for the `Example` class are forwarded to the assembly that now contains the class. The existing application continues to function normally, without recompilation. + +## Forward a type + There are four steps to forwarding a type: 1. Move the source code for the type from the original assembly to the destination assembly. diff --git a/docs/standard/assembly/versioning.md b/docs/standard/assembly/versioning.md index 2c0e556e17d03..c53ce713c9549 100644 --- a/docs/standard/assembly/versioning.md +++ b/docs/standard/assembly/versioning.md @@ -5,7 +5,7 @@ ms.date: "08/20/2019" helpviewer_keywords: - "informational versions" - "version numbers, assemblies" - - "assemblies [.NET Framework], versioning" + - "assemblies [.NET], versioning" - "resolving assembly binding requests" - "versioning, assemblies" ms.assetid: 775ad4fb-914f-453c-98ef-ce1089b6f903 diff --git a/docs/standard/assembly/view-contents.md b/docs/standard/assembly/view-contents.md index e143d2a638341..ddb67af63c768 100644 --- a/docs/standard/assembly/view-contents.md +++ b/docs/standard/assembly/view-contents.md @@ -6,7 +6,7 @@ helpviewer_keywords: - "assembly manifest, viewing information" - "Ildasm.exe" - "MSIL Disassembler" - - "assemblies [.NET Framework], viewing contents" + - "assemblies [.NET], viewing contents" - "viewing assembly information" - "MSIL" - "viewing MSIL information" diff --git a/docs/standard/base-types/type-conversion.md b/docs/standard/base-types/type-conversion.md index d1d76a172d6a4..42c52cd128402 100644 --- a/docs/standard/base-types/type-conversion.md +++ b/docs/standard/base-types/type-conversion.md @@ -1,7 +1,7 @@ --- -title: "Type Conversion in the .NET Framework" +title: "Type Conversion in .NET" description: Read about type conversion in .NET, which creates a value in a new type that's equivalent to the old type's value, but may not keep the original's identity. -ms.date: "03/30/2017" +ms.date: 03/30/2017 ms.technology: dotnet-standard dev_langs: - "csharp" @@ -23,13 +23,14 @@ helpviewer_keywords: - "Convert class" - "implicit conversions" - "Implicit operator" - - "data types [.NET Framework], converting" + - "data types [.NET], converting" ms.assetid: ba36154f-064c-47d3-9f05-72f93a7ca96d --- -# Type Conversion in the .NET Framework +# Type conversion in .NET + Every value has an associated type, which defines attributes such as the amount of space allocated to the value, the range of possible values it can have, and the members that it makes available. Many values can be expressed as more than one type. For example, the value 4 can be expressed as an integer or a floating-point value. Type conversion creates a value in a new type that is equivalent to the value of an old type, but does not necessarily preserve the identity (or exact value) of the original object. - The .NET Framework automatically supports the following conversions: +.NET automatically supports the following conversions: - Conversion from a derived class to a base class. This means, for example, that an instance of any class or structure can be converted to an instance. This conversion does not require a casting or conversion operator. @@ -39,20 +40,21 @@ Every value has an associated type, which defines attributes such as the amount - Conversion from an interface object back to the original type that implements that interface. In C#, this conversion requires a casting operator. In Visual Basic, it requires the `CType` operator if `Option Strict` is on. - In addition to these automatic conversions, the .NET Framework provides several features that support custom type conversion. These include the following: +In addition to these automatic conversions, .NET provides several features that support custom type conversion. These include the following: - The `Implicit` operator, which defines the available widening conversions between types. For more information, see the [Implicit Conversion with the Implicit Operator](#implicit-conversion-with-the-implicit-operator) section. - The `Explicit` operator, which defines the available narrowing conversions between types. For more information, see the [Explicit Conversion with the Explicit Operator](#explicit-conversion-with-the-explicit-operator) section. -- The interface, which defines conversions to each of the base .NET Framework data types. For more information, see [The IConvertible Interface](#the-iconvertible-interface) section. +- The interface, which defines conversions to each of the base .NET data types. For more information, see [The IConvertible Interface](#the-iconvertible-interface) section. - The class, which provides a set of methods that implement the methods in the interface. For more information, see [The Convert Class](#the-convert-class) section. - The class, which is a base class that can be extended to support the conversion of a specified type to any other type. For more information, see [The TypeConverter Class](#the-typeconverter-class) section. -## Implicit Conversion with the Implicit Operator - Widening conversions involve the creation of a new value from the value of an existing type that has either a more restrictive range or a more restricted member list than the target type. Widening conversions cannot result in data loss (although they may result in a loss of precision). Because data cannot be lost, compilers can handle the conversion implicitly or transparently, without requiring the use of an explicit conversion method or a casting operator. +## Implicit conversion with the implicit operator + +Widening conversions involve the creation of a new value from the value of an existing type that has either a more restrictive range or a more restricted member list than the target type. Widening conversions cannot result in data loss (although they may result in a loss of precision). Because data cannot be lost, compilers can handle the conversion implicitly or transparently, without requiring the use of an explicit conversion method or a casting operator. > [!NOTE] > Although code that performs an implicit conversion can call a conversion method or use a casting operator, their use is not required by compilers that support implicit conversions. @@ -72,8 +74,9 @@ Every value has an associated type, which defines attributes such as the amount [!code-csharp[Conceptual.Conversion#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/implicit1.cs#3)] [!code-vb[Conceptual.Conversion#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/implicit1.vb#3)] -## Explicit Conversion with the Explicit Operator - Narrowing conversions involve the creation of a new value from the value of an existing type that has either a greater range or a larger member list than the target type. Because a narrowing conversion can result in a loss of data, compilers often require that the conversion be made explicit through a call to a conversion method or a casting operator. That is, the conversion must be handled explicitly in developer code. +## Explicit conversion with the explicit operator + +Narrowing conversions involve the creation of a new value from the value of an existing type that has either a greater range or a larger member list than the target type. Because a narrowing conversion can result in a loss of data, compilers often require that the conversion be made explicit through a call to a conversion method or a casting operator. That is, the conversion must be handled explicitly in developer code. > [!NOTE] > The major purpose of requiring a conversion method or casting operator for narrowing conversions is to make the developer aware of the possibility of data loss or an so that it can be handled in code. However, some compilers can relax this requirement. For example, in Visual Basic, if `Option Strict` is off (its default setting), the Visual Basic compiler tries to perform narrowing conversions implicitly. @@ -86,12 +89,12 @@ Every value has an associated type, which defines attributes such as the amount || is greater than .| || is greater than .| - To handle such narrowing conversions, the .NET Framework allows types to define an `Explicit` operator. Individual language compilers can then implement this operator using their own syntax, or a member of the class can be called to perform the conversion. (For more information about the class, see [The Convert Class](#the-convert-class) later in this topic.) The following example illustrates the use of language features to handle the explicit conversion of these potentially out-of-range integer values to values. + To handle such narrowing conversions, .NET allows types to define an `Explicit` operator. Individual language compilers can then implement this operator using their own syntax, or a member of the class can be called to perform the conversion. (For more information about the class, see [The Convert Class](#the-convert-class) later in this topic.) The following example illustrates the use of language features to handle the explicit conversion of these potentially out-of-range integer values to values. [!code-csharp[Conceptual.Conversion#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/explicit1.cs#4)] [!code-vb[Conceptual.Conversion#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/explicit1.vb#4)] - Explicit conversions can produce different results in different languages, and these results can differ from the value returned by the corresponding method. For example, if the value 12.63251 is converted to an , both the Visual Basic `CInt` method and the .NET Framework method round the to return a value of 13, but the C# `(int)` operator truncates the to return a value of 12. Similarly, the C# `(int)` operator does not support Boolean-to-integer conversion, but the Visual Basic `CInt` method converts a value of `true` to -1. On the other hand, the method converts a value of `true` to 1. + Explicit conversions can produce different results in different languages, and these results can differ from the value returned by the corresponding method. For example, if the value 12.63251 is converted to an , both the Visual Basic `CInt` method and the .NET method round the to return a value of 13, but the C# `(int)` operator truncates the to return a value of 12. Similarly, the C# `(int)` operator does not support Boolean-to-integer conversion, but the Visual Basic `CInt` method converts a value of `true` to -1. On the other hand, the method converts a value of `true` to 1. Most compilers allow explicit conversions to be performed in a checked or unchecked manner. When a checked conversion is performed, an is thrown when the value of the type to be converted is outside the range of the target type. When an unchecked conversion is performed under the same conditions, the conversion might not throw an exception, but the exact behavior becomes undefined and an incorrect value might result. @@ -112,8 +115,9 @@ Every value has an associated type, which defines attributes such as the amount [!code-csharp[Conceptual.Conversion#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/explicit1.cs#6)] [!code-vb[Conceptual.Conversion#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/explicit1.vb#6)] -## The IConvertible Interface - To support the conversion of any type to a common language runtime base type, the .NET Framework provides the interface. The implementing type is required to provide the following: +## The IConvertible interface + +To support the conversion of any type to a common language runtime base type, .NET provides the interface. The implementing type is required to provide the following: - A method that returns the of the implementing type. @@ -129,20 +133,22 @@ Every value has an associated type, which defines attributes such as the amount The requirement to call the conversion method on its interface rather than on the implementing type makes explicit interface implementations relatively expensive. Instead, we recommend that you call the appropriate member of the class to convert between common language runtime base types. For more information, see the next section, [The Convert Class](#the-convert-class). > [!NOTE] -> In addition to the interface and the class provided by the .NET Framework, individual languages may also provide ways to perform conversions. For example, C# uses casting operators; Visual Basic uses compiler-implemented conversion functions such as `CType`, `CInt`, and `DirectCast`. +> In addition to the interface and the class provided by .NET, individual languages may also provide ways to perform conversions. For example, C# uses casting operators; Visual Basic uses compiler-implemented conversion functions such as `CType`, `CInt`, and `DirectCast`. - For the most part, the interface is designed to support conversion between the base types in the .NET Framework. However, the interface can also be implemented by a custom type to support conversion of that type to other custom types. For more information, see the section [Custom Conversions with the ChangeType Method](#custom-conversions-with-the-changetype-method) later in this topic. + For the most part, the interface is designed to support conversion between the base types in .NET. However, the interface can also be implemented by a custom type to support conversion of that type to other custom types. For more information, see the section [Custom Conversions with the ChangeType Method](#custom-conversions-with-the-changetype-method) later in this topic. -## The Convert Class - Although each base type's interface implementation can be called to perform a type conversion, calling the methods of the class is the recommended language-neutral way to convert from one base type to another. In addition, the method can be used to convert from a specified custom type to another type. +## The Convert class + +Although each base type's interface implementation can be called to perform a type conversion, calling the methods of the class is the recommended language-neutral way to convert from one base type to another. In addition, the method can be used to convert from a specified custom type to another type. -### Conversions Between Base Types - The class provides a language-neutral way to perform conversions between base types and is available to all languages that target the common language runtime. It provides a complete set of methods for both widening and narrowing conversions, and throws an for conversions that are not supported (such as the conversion of a value to an integer value). Narrowing conversions are performed in a checked context, and an is thrown if the conversion fails. +### Conversions between base types + +The class provides a language-neutral way to perform conversions between base types and is available to all languages that target the common language runtime. It provides a complete set of methods for both widening and narrowing conversions, and throws an for conversions that are not supported (such as the conversion of a value to an integer value). Narrowing conversions are performed in a checked context, and an is thrown if the conversion fails. > [!IMPORTANT] > Because the class includes methods to convert to and from each base type, it eliminates the need to call each base type's explicit interface implementation. - The following example illustrates the use of the class to perform several widening and narrowing conversions between .NET Framework base types. + The following example illustrates the use of the class to perform several widening and narrowing conversions between .NET base types. [!code-csharp[Conceptual.Conversion#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/convert1.cs#8)] [!code-vb[Conceptual.Conversion#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/convert1.vb#8)] @@ -154,8 +160,9 @@ Every value has an associated type, which defines attributes such as the amount For a table that lists both the widening and narrowing conversions supported by the class, see [Type Conversion Tables](conversion-tables.md). -### Custom Conversions with the ChangeType Method - In addition to supporting conversions to each of the base types, the class can be used to convert a custom type to one or more predefined types. This conversion is performed by the method, which in turn wraps a call to the method of the `value` parameter. This means that the object represented by the `value` parameter must provide an implementation of the interface. +### Custom conversions with the ChangeType method + +In addition to supporting conversions to each of the base types, the class can be used to convert a custom type to one or more predefined types. This conversion is performed by the method, which in turn wraps a call to the method of the `value` parameter. This means that the object represented by the `value` parameter must provide an implementation of the interface. > [!NOTE] > Because the and methods use a object to specify the target type to which `value` is converted, they can be used to perform a dynamic conversion to an object whose type is not known at compile time. However, note that the implementation of `value` must still support this conversion. @@ -170,8 +177,9 @@ Every value has an associated type, which defines attributes such as the amount [!code-csharp[Conceptual.Conversion#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/iconvertible2.cs#11)] [!code-vb[Conceptual.Conversion#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/iconvertible2.vb#11)] -## The TypeConverter Class - The .NET Framework also allows you to define a type converter for a custom type by extending the class and associating the type converter with the type through a attribute. The following table highlights the differences between this approach and implementing the interface for a custom type. +## The TypeConverter class + +.NET also allows you to define a type converter for a custom type by extending the class and associating the type converter with the type through a attribute. The following table highlights the differences between this approach and implementing the interface for a custom type. > [!NOTE] > Design-time support can be provided for a custom type only if it has a type converter defined for it. diff --git a/docs/standard/building-console-apps.md b/docs/standard/building-console-apps.md index fdf0eec2393aa..9882828d855ce 100644 --- a/docs/standard/building-console-apps.md +++ b/docs/standard/building-console-apps.md @@ -1,29 +1,28 @@ --- -title: "Building Console Applications in .NET" +title: "Create Console Applications in .NET" ms.date: "03/30/2017" ms.technology: dotnet-standard helpviewer_keywords: - - ".NET, building console applications" + - ".NET, creating console applications" - "application development [.NET], console" - "console applications" ms.assetid: c21fb997-9f0e-40a5-8741-f73bba376bd8 --- -# Building Console Applications in .NET +# Console apps in .NET .NET applications can use the class to read characters from and write characters to the console. Data from the console is read from the standard input stream, data to the console is written to the standard output stream, and error data to the console is written to the standard error output stream. These streams are automatically associated with the console when the application starts and are presented as the , , and properties, respectively. - The value of the property is a object, whereas the values of the and properties are objects. You can associate these properties with streams that do not represent the console, making it possible for you to point the stream to a different location for input or output. For example, you can redirect the output to a file by setting the property to a , which encapsulates a by means of the method. The and properties do not need to refer to the same stream. +The value of the property is a object, whereas the values of the and properties are objects. You can associate these properties with streams that do not represent the console, making it possible for you to point the stream to a different location for input or output. For example, you can redirect the output to a file by setting the property to a , which encapsulates a by means of the method. The and properties do not need to refer to the same stream. > [!NOTE] > For more information about building console applications, including examples in C#, Visual Basic, and C++, see the documentation for the class. - If the console does not exist, as in a Windows-based application, output written to the standard output stream will not be visible, because there is no console to write the information to. Writing information to an inaccessible console does not cause an exception to be raised. +If the console does not exist, for example, in a Windows Forms application, output written to the standard output stream will not be visible, because there is no console to write the information to. Writing information to an inaccessible console does not cause an exception to be raised. (You can always change the application type to **Console Application**, for example, in the project property pages in Visual Studio). - Alternately, to enable the console for reading and writing within a Windows-based application that is developed using Visual Studio, open the project's **Properties** dialog box, click the **Application** tab, and set the **Application type** to **Console Application**. +The **System.Console** class has methods that can read individual characters or entire lines from the console. Other methods convert data and format strings, and then write the formatted strings to the console. For more information on formatting strings, see [Formatting types](base-types/formatting-types.md). - Console applications lack a message pump that starts by default. Therefore, console calls to Microsoft Win32 timers might fail. - - The **System.Console** class has methods that can read individual characters or entire lines from the console. Other methods convert data and format strings, and then write the formatted strings to the console. For more information on formatting strings, see [Formatting Types](base-types/formatting-types.md). +> [!TIP] +> Console applications lack a message pump that starts by default. Therefore, console calls to Microsoft Win32 timers might fail. ## See also diff --git a/docs/standard/class-library-overview.md b/docs/standard/class-library-overview.md index 247ef2dc28135..d7d7369b241f9 100644 --- a/docs/standard/class-library-overview.md +++ b/docs/standard/class-library-overview.md @@ -1,49 +1,47 @@ --- title: ".NET class library overview" -description: Learn about the .NET class library. .NET implementations include classes, interfaces, delegates, and value types to provide access to system functionality. +description: Learn about the .NET class library. .NET APIs include classes, interfaces, delegates, and value types to provide access to system functionality. ms.date: "02/08/2018" ms.technology: dotnet-standard helpviewer_keywords: - - "classes [.NET Framework], library overview" - - "classes [.NET Core], library overview" + - "classes [.NET], library overview" - ".NET, library overview" - "class objects value type" - - "naming conventions [.NET Framework]" - - "types, .NET Framework" + - "naming conventions [.NET]" + - "types, .NET" - "user-defined types" - "Visual Basic, data types" - - "data types [.NET Framework], C++" + - "data types [.NET], C++" - "Visual C#, data types" - - "libraries, .NET Framework class library" - - "data types [.NET Framework], F#" + - "libraries, .NET" + - "data types [.NET], F#" - "System namespace" - "F#, data types" - - ".NET Framework, class library" - - "type system [.NET Framework]" - - "data types [.NET Framework]" + - ".NET, class library" + - "type system [.NET]" + - "data types [.NET]" - "value types" - - "data types [.NET Framework], Visual Basic" + - "data types [.NET], Visual Basic" - "Common Language Specification" - - "namespaces [.NET Framework]" + - "namespaces [.NET]" - "floating point value type" - - "class library [.NET Framework]" + - "class library [.NET]" - "CLS" - "logical value type" - - ".NET Framework class library, about" - "built-in types" - - "namespaces [.NET Framework], about namespaces" + - "namespaces [.NET], about namespaces" - "Visual C++, data types" - - "members [.NET Framework], type" - - "data types [.NET Framework], C#" + - "members [.NET], type" + - "data types [.NET], C#" - "integer value type" - "base types, class library" ms.assetid: 7e4c5921-955d-4b06-8709-101873acf157 --- # .NET class library overview -.NET implementations include classes, interfaces, delegates, and value types that expedite and optimize the development process and provide access to system functionality. To facilitate interoperability between languages, most .NET types are CLS-compliant and can therefore be used from any programming language whose compiler conforms to the common language specification (CLS). +.NET APIs include classes, interfaces, delegates, and value types that expedite and optimize the development process and provide access to system functionality. To facilitate interoperability between languages, most .NET types are CLS-compliant and can therefore be used from any programming language whose compiler conforms to the common language specification (CLS). - .NET types are the foundation on which .NET applications, components, and controls are built. .NET implementations include types that perform the following functions: +.NET types are the foundation on which .NET applications, components, and controls are built. .NET includes types that perform the following functions: - Represent base data types and exceptions. @@ -53,29 +51,29 @@ ms.assetid: 7e4c5921-955d-4b06-8709-101873acf157 - Access information about loaded types. -- Invoke .NET Framework security checks. +- Invoke .NET security checks. - Provide data access, rich client-side GUI, and server-controlled, client-side GUI. - .NET provides a rich set of interfaces, as well as abstract and concrete (non-abstract) classes. You can use the concrete classes as is or, in many cases, derive your own classes from them. To use the functionality of an interface, you can either create a class that implements the interface or derive a class from one of the .NET classes that implements the interface. +.NET provides a rich set of interfaces, as well as abstract and concrete (non-abstract) classes. You can use the concrete classes as-is or, in many cases, derive your own classes from them. To use the functionality of an interface, you can either create a class that implements the interface or derive a class from one of the .NET classes that implements the interface. ## Naming conventions .NET types use a dot syntax naming scheme that connotes a hierarchy. This technique groups related types into namespaces so they can be searched and referenced more easily. The first part of the full name — up to the rightmost dot — is the namespace name. The last part of the name is the type name. For example, `System.Collections.Generic.List` represents the `List` type, which belongs to the `System.Collections.Generic` namespace. The types in can be used to work with generic collections. - This naming scheme makes it easy for library developers extending the .NET Framework to create hierarchical groups of types and name them in a consistent, informative manner. It also allows types to be unambiguously identified by their full name (that is, by their namespace and type name), which prevents type name collisions. Library developers are expected to use the following convention when creating names for their namespaces: + This naming scheme makes it easy for library developers extending .NET to create hierarchical groups of types and name them in a consistent, informative manner. It also allows types to be unambiguously identified by their full name (that is, by their namespace and type name), which prevents type name collisions. Library developers are expected to use the following convention when creating names for their namespaces: *CompanyName*.*TechnologyName* For example, the namespace `Microsoft.Word` conforms to this guideline. - The use of naming patterns to group related types into namespaces is a very useful way to build and document class libraries. However, this naming scheme has no effect on visibility, member access, inheritance, security, or binding. A namespace can be partitioned across multiple assemblies and a single assembly can contain types from multiple namespaces. The assembly provides the formal structure for versioning, deployment, security, loading, and visibility in the common language runtime. + The use of naming patterns to group related types into namespaces is a useful way to build and document class libraries. However, this naming scheme has no effect on visibility, member access, inheritance, security, or binding. A namespace can be partitioned across multiple assemblies and a single assembly can contain types from multiple namespaces. The assembly provides the formal structure for versioning, deployment, security, loading, and visibility in the common language runtime. For more information on namespaces and type names, see [Common Type System](base-types/common-type-system.md). ## System namespace - The namespace is the root namespace for fundamental types in .NET. This namespace includes classes that represent the base data types used by all applications: (the root of the inheritance hierarchy), , , , , , and so on. Many of these types correspond to the primitive data types that your programming language uses. When you write code using .NET Framework types, you can use your language's corresponding keyword when a .NET Framework base data type is expected. + The namespace is the root namespace for fundamental types in .NET. This namespace includes classes that represent the base data types used by all applications: (the root of the inheritance hierarchy), , , , , , and so on. Many of these types correspond to the primitive data types that your programming language uses. When you write code using .NET types, you can use your language's corresponding keyword when a .NET base data type is expected. The following table lists the base types that .NET supplies, briefly describes each type, and indicates the corresponding type in Visual Basic, C#, C++, and F#. diff --git a/docs/standard/clr.md b/docs/standard/clr.md index 3575daec7c17a..f7483324177a7 100644 --- a/docs/standard/clr.md +++ b/docs/standard/clr.md @@ -1,7 +1,8 @@ --- -title: "Common Language Runtime (CLR) overview - .NET Framework" -description: Get started with common language runtime (CLR), the .NET run-time environment. The CLR runs code and provides services to make the development process easier. -ms.date: "04/02/2019" +title: "Common Language Runtime (CLR) overview - .NET" +titleSuffix: "" +description: Get started with common language runtime (CLR), .NET's run-time environment. The CLR runs code and provides services to make the development process easier. +ms.date: 10/22/2020 ms.technology: dotnet-standard helpviewer_keywords: - "compiling source code, runtime functionality" @@ -10,7 +11,7 @@ helpviewer_keywords: - "runtime" - "common language runtime" - "metadata, runtime functionality" - - ".NET Framework, common language runtime" + - ".NET, common language runtime" - "language compilers" - "managed code" - "source code execution" @@ -20,16 +21,16 @@ ms.custom: "updateeachrelease" --- # Common Language Runtime (CLR) overview -The .NET Framework provides a run-time environment called the common language runtime, which runs the code and provides services that make the development process easier. +.NET provides a run-time environment, called the common language runtime, that runs the code and provides services that make the development process easier. -Compilers and tools expose the common language runtime's functionality and enable you to write code that benefits from this managed execution environment. Code that you develop with a language compiler that targets the runtime is called managed code; it benefits from features such as cross-language integration, cross-language exception handling, enhanced security, versioning and deployment support, a simplified model for component interaction, and debugging and profiling services. +Compilers and tools expose the common language runtime's functionality and enable you to write code that benefits from this managed execution environment. Code that you develop with a language compiler that targets the runtime is called managed code. Managed code benefits from features such as cross-language integration, cross-language exception handling, enhanced security, versioning and deployment support, a simplified model for component interaction, and debugging and profiling services. > [!NOTE] -> Compilers and tools are able to produce output that the common language runtime can consume because the type system, the format of metadata, and the runtime environment (the virtual execution system) are all defined by a public standard, the ECMA Common Language Infrastructure specification. For more information, see [ECMA C# and Common Language Infrastructure Specifications](https://visualstudio.microsoft.com/license-terms/ecma-c-common-language-infrastructure-standards/). +> Compilers and tools are able to produce output that the common language runtime can consume because the type system, the format of metadata, and the run-time environment (the virtual execution system) are all defined by a public standard, the ECMA Common Language Infrastructure specification. For more information, see [ECMA C# and Common Language Infrastructure Specifications](https://visualstudio.microsoft.com/license-terms/ecma-c-common-language-infrastructure-standards/). To enable the runtime to provide services to managed code, language compilers must emit metadata that describes the types, members, and references in your code. Metadata is stored with the code; every loadable common language runtime portable executable (PE) file contains metadata. The runtime uses metadata to locate and load classes, lay out instances in memory, resolve method invocations, generate native code, enforce security, and set run-time context boundaries. -The runtime automatically handles object layout and manages references to objects, releasing them when they are no longer being used. Objects whose lifetimes are managed in this way are called managed data. Garbage collection eliminates memory leaks as well as some other common programming errors. If your code is managed, you can use managed data, unmanaged data, or both managed and unmanaged data in your .NET Framework application. Because language compilers supply their own types, such as primitive types, you might not always know (or need to know) whether your data is being managed. +The runtime automatically handles object layout and manages references to objects, releasing them when they are no longer being used. Objects whose lifetimes are managed in this way are called managed data. Garbage collection eliminates memory leaks as well as some other common programming errors. If your code is managed, you can use managed data, unmanaged data, or both managed and unmanaged data in your .NET application. Because language compilers supply their own types, such as primitive types, you might not always know (or need to know) whether your data is being managed. The common language runtime makes it easy to design components and applications whose objects interact across languages. Objects written in different languages can communicate with each other, and their behaviors can be tightly integrated. For example, you can define a class and then use a different language to derive a class from your original class or call a method on the original class. You can also pass an instance of a class to a method of a class written in a different language. This cross-language integration is possible because language compilers and tools that target the runtime use a common type system defined by the runtime, and they follow the runtime's rules for defining new types, as well as for creating, using, persisting, and binding to types. @@ -57,7 +58,9 @@ Language compilers and tools expose the runtime's functionality in ways that are ## CLR versions -The .NET Framework version number doesn't necessarily correspond to the version number of the CLR it includes. For a list of .NET Framework versions and their corresponding CLR versions, see [.NET Framework versions and dependencies](../framework/migration-guide/versions-and-dependencies.md). .NET Core releases have a single product version, that is, there is no separate CLR version. For a list of .NET Core versions, see [Download .NET Core](https://dotnet.microsoft.com/download/dotnet-core). +.NET Core and .NET 5+ releases have a single product version, that is, there is no separate CLR version. For a list of .NET Core versions, see [Download .NET Core](https://dotnet.microsoft.com/download/dotnet-core). + +However, the .NET Framework version number doesn't necessarily correspond to the version number of the CLR it includes. For a list of .NET Framework versions and their corresponding CLR versions, see [.NET Framework versions and dependencies](../framework/migration-guide/versions-and-dependencies.md). ## Related topics @@ -65,5 +68,5 @@ The .NET Framework version number doesn't necessarily correspond to the version |-----------|-----------------| |[Managed Execution Process](managed-execution-process.md)|Describes the steps required to take advantage of the common language runtime.| |[Automatic Memory Management](automatic-memory-management.md)|Describes how the garbage collector allocates and releases memory.| -|[Overview of the .NET Framework](../framework/get-started/overview.md)|Describes key .NET Framework concepts such as the common type system, cross-language interoperability, managed execution, application domains, and assemblies.| +|[Overview of .NET Framework](../framework/get-started/overview.md)|Describes key .NET Framework concepts, such as the common type system, cross-language interoperability, managed execution, application domains, and assemblies.| |[Common Type System](./base-types/common-type-system.md)|Describes how types are declared, used, and managed in the runtime in support of cross-language integration.| diff --git a/docs/standard/data/xml/converting-dotnet-types-to-strings.md b/docs/standard/data/xml/converting-dotnet-types-to-strings.md index 443e9a8251934..5c28c7faf8e09 100644 --- a/docs/standard/data/xml/converting-dotnet-types-to-strings.md +++ b/docs/standard/data/xml/converting-dotnet-types-to-strings.md @@ -1,13 +1,14 @@ --- -title: "Converting .NET Framework Types to Strings" +title: "Converting .NET Types to Strings" ms.date: "03/30/2017" ms.technology: dotnet-standard ms.assetid: dc2e2b65-f623-4dc3-938b-d2a054d6832c --- -# Converting .NET Framework Types to Strings -If you want to convert a .NET Framework type to a string, use the **ToString** method. The **ToString** method returns a string representation of the type passed in. The following table lists the .NET Framework types that return a string in a format that maps to the XML Schema (XSD) specifications. +# Convert .NET types to strings + +If you want to convert a .NET type to a string, use the **ToString** method. The **ToString** method returns a string representation of the type passed in. The following table lists the .NET types that return a string in a format that maps to the XML Schema (XSD) specifications. -|.NET Framework type|String type returned| +|.NET type|String type returned| |-------------------------|--------------------------| |Boolean|"true", "false"| |Single.PositiveInfinity|"INF"| @@ -20,4 +21,4 @@ If you want to convert a .NET Framework type to a string, use the **ToString** m ## See also - [Conversion of XML Data Types](conversion-of-xml-data-types.md) -- [Converting Strings to .NET Framework Data Types](converting-strings-to-dotnet-data-types.md) +- [Converting Strings to .NET Data Types](converting-strings-to-dotnet-data-types.md) diff --git a/docs/standard/data/xml/converting-strings-to-dotnet-data-types.md b/docs/standard/data/xml/converting-strings-to-dotnet-data-types.md index a63ee694147a8..c3e2bc874e277 100644 --- a/docs/standard/data/xml/converting-strings-to-dotnet-data-types.md +++ b/docs/standard/data/xml/converting-strings-to-dotnet-data-types.md @@ -1,5 +1,5 @@ --- -title: "Converting Strings to .NET Framework Data Types" +title: "Converting Strings to .NET Data Types" ms.date: "03/30/2017" ms.technology: dotnet-standard dev_langs: @@ -7,14 +7,15 @@ dev_langs: - "vb" ms.assetid: 65455ef3-9120-412c-819b-d0f59f88ac09 --- -# Converting Strings to .NET Framework Data Types -If you want to convert a string to a .NET Framework data type, use the **XmlConvert** method that fits the application requirements. For a list of all conversion methods available in the **XmlConvert** class, see . +# Convert strings to .NET data types + +If you want to convert a string to a .NET data type, use the **XmlConvert** method that fits the application requirements. For a list of all conversion methods available in the **XmlConvert** class, see . - The string returned from the **ToString** method is a string version of the data that is passed in. Additionally, there are several .NET Framework types that convert using the **XmlConvert** class yet they do not use the methods in the **System.Convert** class. The **XmlConvert** class follows the XML Schema (XSD) data type specification and has a data type that the **XmlConvert** can map to. + The string returned from the **ToString** method is a string version of the data that is passed in. Additionally, there are several .NET types that convert using the **XmlConvert** class yet they do not use the methods in the **System.Convert** class. The **XmlConvert** class follows the XML Schema (XSD) data type specification and has a data type that the **XmlConvert** can map to. - The following table lists .NET Framework data types and the string types that are returned using XML Schema (XSD) data type mapping. These .NET Framework types cannot be processed using **System.Convert**. + The following table lists .NET data types and the string types that are returned using XML Schema (XSD) data type mapping. These .NET types cannot be processed using **System.Convert**. -|.NET Framework type|String returned| +|.NET type|String returned| |-------------------------|---------------------| |Boolean|"true", "false"| |Single.PositiveInfinity|"INF"| @@ -25,7 +26,7 @@ If you want to convert a string to a .NET Framework data type, use the **XmlConv |Timespan|Format is PnYnMnTnHnMnS that is, `P2Y10M15DT10H30M20S` is a duration of 2 years, 10 months, 15 days, 10 hours, 30 minutes, and 20 seconds.| > [!NOTE] -> If converting any of the .NET Framework types listed in the table to a string using the **ToString** method, the returned string is not the base type, but the XML Schema (XSD) string type. +> If converting any of the .NET types listed in the table to a string using the **ToString** method, the returned string is not the base type, but the XML Schema (XSD) string type. The **DateTime** and **Timespan** value type differs in that a **DateTime** represents an instant in time, whereas a **TimeSpan** represents a time interval. The **DateTime** and **Timespan** formats are specified in the XML Schema (XSD) data types specification. For example: @@ -63,12 +64,12 @@ writer.WriteElementString("Number", XmlConvert.ToString(value)); `200` - However, if you are converting a string to **Boolean**, **Single**, or **Double**, the .NET Framework type that is returned is not the same as the type returned when using the **System.Convert** class. + However, if you are converting a string to **Boolean**, **Single**, or **Double**, the .NET type that's returned is not the same as the type returned when using the **System.Convert** class. ## String to Boolean The following table shows what type is generated for the given input strings, when converting a string to **Boolean** using the **ToBoolean** method. -|Valid string input parameter|.NET Framework output type| +|Valid string input parameter|.NET output type| |----------------------------------|--------------------------------| |"true"|Boolean.True| |"1"|Boolean.True| @@ -100,7 +101,7 @@ Console.WriteLine(bvalue); ## String to Single The following table shows what type is generated for the given input strings, when converting a string to a **Single** using the **ToSingle** method. -|Valid string input parameter|.NET Framework output type| +|Valid string input parameter|.NET output type| |----------------------------------|--------------------------------| |"INF"|Single.PositiveInfinity| |"-INF"|Single.NegativeInfinity| @@ -108,7 +109,7 @@ Console.WriteLine(bvalue); ## String to Double The following table shows what type is generated for the given input strings, when converting a string to a **Single** using the **ToDouble** method. -|Valid string input parameter|.NET Framework output type| +|Valid string input parameter|.NET output type| |----------------------------------|--------------------------------| |"INF"|Double.PositiveInfinity| |"-INF"|Double.NegativeInfinity| @@ -128,4 +129,4 @@ writer.WriteElementString("Infinity", XmlConvert.ToString(value)); ## See also - [Conversion of XML Data Types](conversion-of-xml-data-types.md) -- [Converting .NET Framework Types to Strings](converting-dotnet-types-to-strings.md) +- [Converting .NET Types to Strings](converting-dotnet-types-to-strings.md) diff --git a/docs/standard/events/how-to-consume-events-in-a-web-forms-application.md b/docs/standard/events/how-to-consume-events-in-a-web-forms-application.md deleted file mode 100644 index 29d692499eb50..0000000000000 --- a/docs/standard/events/how-to-consume-events-in-a-web-forms-application.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "How to: Consume Events in a Web Forms Application" -ms.date: "03/30/2017" -ms.technology: dotnet-standard -dev_langs: - - "csharp" - - "vb" -helpviewer_keywords: - - "events [.NET Framework], Web Forms" - - "Web Forms controls, and events" - - "event handlers [.NET Framework], Web Forms" - - "events [.NET Framework], consuming" - - "Web Forms, event handling" -ms.assetid: 73bf8638-c4ec-4069-b0bb-a1dc79b92e32 ---- -# How to: Consume Events in a Web Forms Application -A common scenario in ASP.NET Web Forms applications is to populate a webpage with controls, and then perform a specific action based on which control the user clicks. For example, a control raises an event when the user clicks it in the webpage. By handling the event, your application can perform the appropriate application logic for that button click. - -### To handle a button click event on a webpage - -1. Create a ASP.NET Web Forms page (webpage) that has a control with the `OnClick` value set to the name of method that you will define in the next step. - - ```xml - - ``` - -2. Define an event handler that matches the event delegate signature and that has the name you defined for the `OnClick` value. - - ```csharp - protected void Button1_Click(object sender, EventArgs e) - { - // perform action - } - ``` - - ```vb - Protected Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click - ' perform action - End Sub - ``` - - The event uses the class for the delegate type and the class for the event data. The ASP.NET page framework automatically generates code that creates an instance of and adds this delegate instance to the event of the instance. - -3. In the event handler method that you defined in step 2, add code to perform any actions that are required when the event occurs. - -## See also - -- [Events](index.md) diff --git a/docs/standard/events/index.md b/docs/standard/events/index.md index af90b8e3a0fe8..971ec0b14b72a 100644 --- a/docs/standard/events/index.md +++ b/docs/standard/events/index.md @@ -10,21 +10,19 @@ helpviewer_keywords: - "delegate model for events" - "application development [.NET], events" - "application development [.NET Framework], events" - - "application development [.NET Core], events" + - "application development [.NET Core], events" - "events [.NET]" - "events [.NET Core]" - "events [.NET Framework]" ms.assetid: b6f65241-e0ad-4590-a99f-200ce741bb1f --- -# Handling and raising events +# Handle and raising events -Events in .NET are based on the delegate model. The delegate model follows the [observer design pattern](observer-design-pattern.md), which enables a subscriber to register with and receive notifications from a provider. An event sender pushes a notification that an event has happened, and an event receiver receives that notification and defines a response to it. This article describes the major components of the delegate model, how to consume events in applications, and how to implement events in your code. - - For information about handling events in Windows 8.x Store apps, see [Events and routed events overview](/previous-versions/windows/apps/hh758286(v=win.10)). +Events in .NET are based on the delegate model. The delegate model follows the [observer design pattern](observer-design-pattern.md), which enables a subscriber to register with and receive notifications from a provider. An event sender pushes a notification that an event has happened, and an event receiver receives that notification and defines a response to it. This article describes the major components of the delegate model, how to consume events in applications, and how to implement events in your code. ## Events -An event is a message sent by an object to signal the occurrence of an action. The action can be caused by user interaction, such as a button click, or it can result from some other program logic, such as changing a property’s value. The object that raises the event is called the *event sender*. The event sender doesn't know which object or method will receive (handle) the events it raises. The event is typically a member of the event sender; for example, the event is a member of the class, and the event is a member of the class that implements the interface. +An event is a message sent by an object to signal the occurrence of an action. The action can be caused by user interaction, such as a button click, or it can result from some other program logic, such as changing a property's value. The object that raises the event is called the *event sender*. The event sender doesn't know which object or method will receive (handle) the events it raises. The event is typically a member of the event sender; for example, the event is a member of the class, and the event is a member of the class that implements the interface. To define an event, you use the C# [`event`](../../csharp/language-reference/keywords/event.md) or the Visual Basic [`Event`](../../visual-basic/language-reference/statements/event-statement.md) keyword in the signature of your event class, and specify the type of delegate for the event. Delegates are described in the next section. @@ -76,19 +74,19 @@ The following example shows an event handler method named `c_ThresholdReached` t .NET allows subscribers to register for event notifications either statically or dynamically. Static event handlers are in effect for the entire life of the class whose events they handle. Dynamic event handlers are explicitly activated and deactivated during program execution, usually in response to some conditional program logic. For example, they can be used if event notifications are needed only under certain conditions or if an application provides multiple event handlers and run-time conditions define the appropriate one to use. The example in the previous section shows how to dynamically add an event handler. For more information, see [Events](../../visual-basic/programming-guide/language-features/events/index.md) (in Visual Basic) and [Events](../../csharp/programming-guide/events/index.md) (in C#). -## Raising multiple events +## Raising multiple events + If your class raises multiple events, the compiler generates one field per event delegate instance. If the number of events is large, the storage cost of one field per delegate may not be acceptable. For those situations, .NET provides event properties that you can use with another data structure of your choice to store event delegates. Event properties consist of event declarations accompanied by event accessors. Event accessors are methods that you define to add or remove event delegate instances from the storage data structure. Note that event properties are slower than event fields, because each event delegate must be retrieved before it can be invoked. The trade-off is between memory and speed. If your class defines many events that are infrequently raised, you will want to implement event properties. For more information, see [How to: Handle Multiple Events Using Event Properties](how-to-handle-multiple-events-using-event-properties.md). -## Related topics +## Related articles |Title|Description| |-----------|-----------------| |[How to: Raise and Consume Events](how-to-raise-and-consume-events.md)|Contains examples of raising and consuming events.| |[How to: Handle Multiple Events Using Event Properties](how-to-handle-multiple-events-using-event-properties.md)|Shows how to use event properties to handle multiple events.| -|[Observer Design Pattern](observer-design-pattern.md)|Describes the design pattern that enables a subscriber to register with, and receive notifications from, a provider.| -|[How to: Consume Events in a Web Forms Application](how-to-consume-events-in-a-web-forms-application.md)|Shows how to handle an event that is raised by a Web Forms control.| +|[Observer Design Pattern](observer-design-pattern.md)|Describes the design pattern that enables a subscriber to register with, and receive notifications from, a provider.| ## See also @@ -99,3 +97,4 @@ The following example shows an event handler method named `c_ThresholdReached` t - [Events (Visual Basic)](../../visual-basic/programming-guide/language-features/events/index.md) - [Events (C# Programming Guide)](../../csharp/programming-guide/events/index.md) - [Events and routed events overview (UWP apps)](/windows/uwp/xaml-platform/events-and-routed-events-overview) +- [Events in Windows Store 8.x apps](/previous-versions/windows/apps/hh758286(v=win.10)) diff --git a/docs/standard/garbage-collection/implementing-disposeasync.md b/docs/standard/garbage-collection/implementing-disposeasync.md index d004aa5c4cc7b..681d3a6d24a8a 100644 --- a/docs/standard/garbage-collection/implementing-disposeasync.md +++ b/docs/standard/garbage-collection/implementing-disposeasync.md @@ -3,7 +3,7 @@ title: Implement a DisposeAsync method description: Learn how to implement DisposeAsync and DisposeAsyncCore methods to perform asynchronous resource cleanup. author: IEvangelist ms.author: dapine -ms.date: 09/16/2020 +ms.date: 10/26/2020 ms.technology: dotnet-standard dev_langs: - "csharp" @@ -97,9 +97,34 @@ Furthermore, it could be written to use the implicit scoping of a [using declara ## Stacked usings -In situations where you create and use multiple objects that implement , it's possible that stacking `using` statements in errant conditions could prevent calls to . In order to help prevent potential concern, you should avoid stacking, and instead follow this example pattern: +In situations where you create and use multiple objects that implement , it's possible that stacking `await using` statements with could prevent calls to in errant conditions. To ensure that is always called, you should avoid stacking. The following three code examples show acceptable patterns to use instead. -:::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs"::: +### Acceptable pattern one + +:::code language="csharp" id="one" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs"::: + +In the preceding example, each asynchronous clean up operation is explicitly scoped under the `await using` block. The outer scope is defined by how `objOne` sets its braces, enclosing `objTwo`, as such `objTwo` is disposed first, followed by `objOne`. Both `IAsyncDisposable` instances have there methods awaited, thus performing its asynchronous clean up operation. The calls are nested, not stacked. + +### Acceptable pattern two + +:::code language="csharp" id="two" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs"::: + +In the preceding example, each asynchronous clean up operation is explicitly scoped under the `await using` block. At the end of each block, the corresponding `IAsyncDisposable` instance has its method awaited, thus performing its asynchronous clean up operation. The calls are sequential, not stacked. In this scenario `objOne` is disposed first, then `objTwo` is disposed. + +### Acceptable pattern three + +:::code language="csharp" id="three" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs"::: + +In the preceding example, each asynchronous clean up operation is implicitly scoped with the containing method body. At the end of the enclosing block, the `IAsyncDisposable` instances perform their asynchronous clean up operations. This runs in reverse order from which they were declared, meaning that `objTwo` is disposed before `objOne`. + +### Unacceptable pattern + +If an exception is thrown from the `AnotherAsyncDisposable` constructor, then `objOne` does not get properly disposed: + +:::code language="csharp" id="dontdothis" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs"::: + +> [!TIP] +> Avoid this pattern as it could lead to unexpected behavior. ## See also diff --git a/docs/standard/numerics.md b/docs/standard/numerics.md index 8113a0112e997..bdd459eb69b7f 100644 --- a/docs/standard/numerics.md +++ b/docs/standard/numerics.md @@ -82,10 +82,11 @@ The .NET SIMD-enabled types include the following: - The type, which represents a vector that is used to encode three-dimensional physical rotations. - The type, which represents a vector of a specified numeric type and provides a broad set of operators that benefit from SIMD support. The count of a instance is fixed, but its value depends on the CPU of the machine, on which code is executed. + > [!NOTE] - > The type is not included into the .NET Framework. You must install the [System.Numerics.Vectors](https://www.nuget.org/packages/System.Numerics.Vectors) NuGet package to get access to this type. + > The type is included with .NET Core and .NET 5+, but not .NET Framework. If you're using .NET Framework, install the [System.Numerics.Vectors](https://www.nuget.org/packages/System.Numerics.Vectors) NuGet package to get access to this type. -The SIMD-enabled types are implemented in such a way that they can be used with non-SIMD-enabled hardware or JIT compilers. To take advantage of SIMD instructions, your 64-bit apps must be run by the runtime that uses the RyuJIT compiler, which is included in .NET Core and in the .NET Framework 4.6 and later versions. It adds SIMD support when targeting 64-bit processors. +The SIMD-enabled types are implemented in such a way that they can be used with non-SIMD-enabled hardware or JIT compilers. To take advantage of SIMD instructions, your 64-bit apps must be run by the runtime that uses the RyuJIT compiler, which is included in .NET Core and in .NET Framework 4.6 and later versions. It adds SIMD support when targeting 64-bit processors. For more information, see [Use SIMD-accelerated numeric types](simd.md). diff --git a/docs/standard/parallel-programming/task-parallel-library-tpl.md b/docs/standard/parallel-programming/task-parallel-library-tpl.md index c5debd88bdb7a..9c147581c92c7 100644 --- a/docs/standard/parallel-programming/task-parallel-library-tpl.md +++ b/docs/standard/parallel-programming/task-parallel-library-tpl.md @@ -12,7 +12,7 @@ ms.assetid: b8f99f43-9104-45fd-9bff-385a20488a23 # Task Parallel Library (TPL) The Task Parallel Library (TPL) is a set of public types and APIs in the and namespaces. The purpose of the TPL is to make developers more productive by simplifying the process of adding parallelism and concurrency to applications. The TPL scales the degree of concurrency dynamically to most efficiently use all the processors that are available. In addition, the TPL handles the partitioning of the work, the scheduling of threads on the , cancellation support, state management, and other low-level details. By using TPL, you can maximize the performance of your code while focusing on the work that your program is designed to accomplish. - Starting with the .NET Framework 4, the TPL is the preferred way to write multithreaded and parallel code. However, not all code is suitable for parallelization; for example, if a loop performs only a small amount of work on each iteration, or it doesn't run for many iterations, then the overhead of parallelization can cause the code to run more slowly. Furthermore, parallelization like any multithreaded code adds complexity to your program execution. Although the TPL simplifies multithreaded scenarios, we recommend that you have a basic understanding of threading concepts, for example, locks, deadlocks, and race conditions, so that you can use the TPL effectively. + Starting with .NET Framework 4, the TPL is the preferred way to write multithreaded and parallel code. However, not all code is suitable for parallelization; for example, if a loop performs only a small amount of work on each iteration, or it doesn't run for many iterations, then the overhead of parallelization can cause the code to run more slowly. Furthermore, parallelization like any multithreaded code adds complexity to your program execution. Although the TPL simplifies multithreaded scenarios, we recommend that you have a basic understanding of threading concepts, for example, locks, deadlocks, and race conditions, so that you can use the TPL effectively. ## Related Topics diff --git a/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md b/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md index 0e954dce2b357..2ffc5a0cb2ee0 100644 --- a/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md +++ b/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md @@ -1,6 +1,6 @@ --- -title: "TPL and Traditional .NET Framework Asynchronous Programming" -ms.date: "03/30/2017" +title: "TPL and Traditional .NET Asynchronous Programming" +ms.date: 03/30/2017 ms.technology: dotnet-standard dev_langs: - "csharp" @@ -9,38 +9,40 @@ helpviewer_keywords: - "tasks, with other asynchronous models" ms.assetid: e7b31170-a156-433f-9f26-b1fc7cd1776f --- -# TPL and Traditional .NET Framework Asynchronous Programming -The .NET Framework provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations: +# TPL and traditional .NET asynchronous programming + +.NET provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations: -- Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of Begin/End methods such as and . +- Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of begin/end methods. For example: and . -- Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named *OperationName*Async and *OperationName*Completed, for example, and . (EAP was introduced in the .NET Framework version 2.0.) +- Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named `Async` and `Completed`. For example: and . - The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. You can expose both APM and EAP operations as Tasks to library consumers, or you can expose the APM patterns but use Task objects to implement them internally. In both scenarios, by using Task objects, you can simplify the code and take advantage of the following useful functionality: +The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. You can expose both APM and EAP operations as `Task` objects to library consumers, or you can expose the APM patterns but use `Task` objects to implement them internally. In both scenarios, by using `Task` objects, you can simplify the code and take advantage of the following useful functionality: - Register callbacks, in the form of task continuations, at any time after the task has started. -- Coordinate multiple operations that execute in response to a `Begin_` method, by using the and methods, or the method or the method. +- Coordinate multiple operations that execute in response to a `Begin_` method by using the and methods, or the and methods. -- Encapsulate asynchronous I/O-bound and compute-bound operations in the same Task object. +- Encapsulate asynchronous I/O-bound and compute-bound operations in the same `Task` object. -- Monitor the status of the Task object. +- Monitor the status of the `Task` object. -- Marshal the status of an operation to a Task object by using . +- Marshal the status of an operation to a `Task` object by using . -## Wrapping APM Operations in a Task - Both the and classes provide several overloads of the and methods that let you encapsulate an APM Begin/End method pair in one or instance. The various overloads accommodate any Begin/End method pair that have from zero to three input parameters. +## Wrap APM operations in a Task + + Both the and classes provide several overloads of the and methods that let you encapsulate an APM begin/end method pair in one or instance. The various overloads accommodate any begin/end method pair that have from zero to three input parameters. - For pairs that have `End` methods that return a value (`Function` in Visual Basic), use the methods in that create a . For `End` methods that return void (`Sub` in Visual Basic), use the methods in that create a . + For pairs that have `End` methods that return a value (a `Function` in Visual Basic), use the methods in that create a . For `End` methods that return void (a `Sub` in Visual Basic), use the methods in that create a . For those few cases in which the `Begin` method has more than three parameters or contains `ref` or `out` parameters, additional `FromAsync` overloads that encapsulate only the `End` method are provided. - The following example shows the signature for the `FromAsync` overload that matches the and methods. This overload takes three input parameters, as follows. + The following example shows the signature for the `FromAsync` overload that matches the and methods. [!code-csharp[FromAsync#01](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#01)] [!code-vb[FromAsync#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#01)] - The first parameter is a delegate that matches the signature of the method. The second parameter is a delegate that takes an and returns a `TResult`. Because returns an integer, the compiler infers the type of `TResult` as and the type of the task as . The last four parameters are identical to those in the method: +This overload takes three input parameters, as follows. The first parameter is a delegate that matches the signature of the method. The second parameter is a delegate that takes an and returns a `TResult`. Because returns an integer, the compiler infers the type of `TResult` as and the type of the task as . The last four parameters are identical to those in the method: - The buffer in which to store the file data. @@ -50,10 +52,11 @@ The .NET Framework provides the following two standard patterns for performing I - An optional object that stores user-defined state data to pass to the callback. -### Using ContinueWith for the Callback Functionality +### Use ContinueWith for the callback functionality + If you require access to the data in the file, as opposed to just the number of bytes, the method is not sufficient. Instead, use , whose `Result` property contains the file data. You can do this by adding a continuation to the original task. The continuation performs the work that would typically be performed by the delegate. It is invoked when the antecedent completes, and the data buffer has been filled. (The object should be closed before returning.) - The following example shows how to return a that encapsulates the BeginRead/EndRead pair of the class. + The following example shows how to return a that encapsulates the `BeginRead`/`EndRead` pair of the class. [!code-csharp[FromAsync#03](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#03)] [!code-vb[FromAsync#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#03)] @@ -63,32 +66,37 @@ The .NET Framework provides the following two standard patterns for performing I [!code-csharp[FromAsync#04](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#04)] [!code-vb[FromAsync#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#04)] -### Providing Custom State Data +### Provide custom state data + In typical operations, if your delegate requires some custom state data, you have to pass it in through the last parameter in the `Begin` method, so that the data can be packaged into the object that is eventually passed to the callback method. This is typically not required when the `FromAsync` methods are used. If the custom data is known to the continuation, then it can be captured directly in the continuation delegate. The following example resembles the previous example, but instead of examining the `Result` property of the antecedent, the continuation examines the custom state data that is directly accessible to the user delegate of the continuation. [!code-csharp[FromAsync#05](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#05)] [!code-vb[FromAsync#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#05)] -### Synchronizing Multiple FromAsync Tasks +### Synchronize multiple FromAsync tasks + The static and methods provide added flexibility when used in conjunction with the `FromAsync` methods. The following example shows how to initiate multiple asynchronous I/O operations, and then wait for all of them to complete before you execute the continuation. [!code-csharp[FromAsync#06](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#06)] [!code-vb[FromAsync#06](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#06)] -### FromAsync Tasks For Only the End Method - For those few cases in which the `Begin` method requires more than three input parameters, or has `ref` or `out` parameters, you can use the `FromAsync` overloads, for example, , that represent only the `End` method. These methods can also be used in any scenario in which you are passed an and want to encapsulate it in a Task. +### FromAsync tasks for only the End method + + For those few cases in which the `Begin` method requires more than three input parameters or has `ref` or `out` parameters, you can use the `FromAsync` overloads, for example, , that represent only the `End` method. These methods can also be used in any scenario in which you're passed an and want to encapsulate it in a Task. [!code-csharp[FromAsync#07](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#07)] [!code-vb[FromAsync#07](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#07)] -### Starting and Canceling FromAsync Tasks - The task returned by a `FromAsync` method has a status of WaitingForActivation and will be started by the system at some point after the task is created. If you attempt to call Start on such a task, an exception will be raised. +### Start and cancel FromAsync tasks + + The task returned by a `FromAsync` method has a status of `WaitingForActivation` and will be started by the system at some point after the task is created. If you attempt to call Start on such a task, an exception will be raised. - You cannot cancel a `FromAsync` task, because the underlying .NET Framework APIs currently do not support in-progress cancellation of file or network I/O. You can add cancellation functionality to a method that encapsulates a `FromAsync` call, but you can only respond to the cancellation before `FromAsync` is called or after it completed (for example, in a continuation task). + You cannot cancel a `FromAsync` task, because the underlying .NET APIs currently do not support in-progress cancellation of file or network I/O. You can add cancellation functionality to a method that encapsulates a `FromAsync` call, but you can only respond to the cancellation before `FromAsync` is called or after it completed (for example, in a continuation task). Some classes that support EAP, for example, , do support cancellation, and you can integrate that native cancellation functionality by using cancellation tokens. -## Exposing Complex EAP Operations As Tasks +## Expose complex EAP operations As tasks + The TPL does not provide any methods that are specifically designed to encapsulate an event-based asynchronous operation in the same way that the `FromAsync` family of methods wrap the pattern. However, the TPL does provide the class, which can be used to represent any arbitrary set of operations as a . The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both. The following example shows how to use a to expose a set of asynchronous operations to client code as a basic . The method lets you enter an array of Web URLs, and a term or name to search for, and then returns the number of times the search term occurs on each site. @@ -98,17 +106,19 @@ The .NET Framework provides the following two standard patterns for performing I For a more complete example, which includes additional exception handling and shows how to call the method from client code, see [How to: Wrap EAP Patterns in a Task](how-to-wrap-eap-patterns-in-a-task.md). - Remember that any task that is created by a will be started by that TaskCompletionSource and, therefore, user code should not call the Start method on that task. + Remember that any task that's created by a will be started by that `TaskCompletionSource` and, therefore, user code should not call the `Start` method on that task. -## Implementing the APM Pattern By Using Tasks - In some scenarios, it may be desirable to directly expose the pattern by using Begin/End method pairs in an API. For example, you may want to maintain consistency with existing APIs, or you may have automated tools that require this pattern. In such cases, you can use Tasks to simplify how the APM pattern is implemented internally. +## Implement the APM pattern by using tasks + + In some scenarios, it may be desirable to directly expose the pattern by using begin/end method pairs in an API. For example, you may want to maintain consistency with existing APIs, or you may have automated tools that require this pattern. In such cases, you can use `Task` objects to simplify how the APM pattern is implemented internally. - The following example shows how to use tasks to implement an APM Begin/End method pair for a long-running compute-bound method. + The following example shows how to use tasks to implement an APM begin/end method pair for a long-running compute-bound method. [!code-csharp[FromAsync#09](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#09)] [!code-vb[FromAsync#09](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#09)] -## Using the StreamExtensions Sample Code +## Use the StreamExtensions sample code + The *StreamExtensions.cs* file, in the [.NET Standard parallel extensions extras](/samples/dotnet/samples/parallel-programming-extensions-extras-cs/) repository, contains several reference implementations that use `Task` objects for asynchronous file and network I/O. ## See also diff --git a/samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/anotherasyncdisposable.cs b/samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/anotherasyncdisposable.cs new file mode 100644 index 0000000000000..b9e41603e6874 --- /dev/null +++ b/samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/anotherasyncdisposable.cs @@ -0,0 +1,9 @@ +using System; +using System.Threading.Tasks; + +public class AnotherAsyncDisposable : IAsyncDisposable +{ + public AnotherAsyncDisposable() => throw new Exception("Oops, sorry..."); + + public ValueTask DisposeAsync() => new ValueTask(); +} diff --git a/samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs b/samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs index 15ee39863727b..df3ad21316fa9 100644 --- a/samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs +++ b/samples/snippets/csharp/VS_Snippets_CLR/conceptual.asyncdisposable/stacked-await-usings.cs @@ -1,7 +1,30 @@ -using System; +// +using System; using System.Threading.Tasks; -class ExampleStackedProgram +class ExampleOneProgram +{ + static async Task Main() + { + var objOne = new ExampleAsyncDisposable(); + await using (objOne.ConfigureAwait(false)) + { + // Interact with the objOne instance. + + var objTwo = new ExampleAsyncDisposable(); + await using (objTwo.ConfigureAwait(false)) + { + // Interact with the objOne and/or objTwo instance(s). + } + } + + Console.ReadLine(); + } +} +// + +// +class ExampleTwoProgram { static async Task Main() { @@ -20,3 +43,42 @@ static async Task Main() Console.ReadLine(); } } +// + +// +class ExampleThreeProgram +{ + static async Task Main() + { + var objOne = new ExampleAsyncDisposable(); + await using var ignored1 = objOne.ConfigureAwait(false); + + var objTwo = new ExampleAsyncDisposable(); + await using var ignored2 = objTwo.ConfigureAwait(false); + + // Interact with objOne and/or objTwo instance(s). + + Console.ReadLine(); + } +} +// + +// +class DoNotDoThisProgram +{ + static async Task Main() + { + var objOne = new ExampleAsyncDisposable(); + // Exception thrown on .ctor + var objTwo = new AnotherAsyncDisposable(); + + await using (objOne.ConfigureAwait(false)) + await using (objTwo.ConfigureAwait(false)) + { + // Only objOne has its DisposeAsync called. + } + + Console.ReadLine(); + } +} +//