diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index a7c6b99f845df..25638945abfa1 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -28,6 +28,7 @@ See [Breaking changes in ASP.NET Core 10](/aspnet/core/breaking-changes/10/overv | [Environment.TickCount made consistent with Windows timeout behavior](core-libraries/11/environment-tickcount-windows-behavior.md) | Behavioral change | | [MemoryStream maximum capacity updated and exception behavior changed](core-libraries/11/memorystream-max-capacity.md) | Behavioral change | | [TAR-reading APIs verify header checksums when reading](core-libraries/11/tar-checksum-validation.md) | Behavioral change | +| [ZipArchive.CreateAsync eagerly loads ZIP archive entries](core-libraries/11/ziparchive-createasync-eager-load.md) | Behavioral change | ## Cryptography @@ -52,3 +53,9 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking- | Title | Type of change | |-------------------------------------------------------------------|-------------------| | [Minimum hardware requirements updated](jit/11/minimum-hardware-requirements.md) | Behavioral change | + +## SDK and MSBuild + +| Title | Type of change | +|-------------------------------------------------------------------|-------------------| +| [mono launch target not set for .NET Framework apps](sdk/11/mono-launch-target-removed.md) | Behavioral change | diff --git a/docs/core/compatibility/core-libraries/11/ziparchive-createasync-eager-load.md b/docs/core/compatibility/core-libraries/11/ziparchive-createasync-eager-load.md new file mode 100644 index 0000000000000..1aeb9959d311d --- /dev/null +++ b/docs/core/compatibility/core-libraries/11/ziparchive-createasync-eager-load.md @@ -0,0 +1,67 @@ +--- +title: "Breaking change: ZipArchive.CreateAsync eagerly loads ZIP archive entries" +description: "Learn about the breaking change in .NET 11 where ZipArchive.CreateAsync eagerly loads all ZIP archive entries to avoid synchronous reads on the stream." +ms.date: 02/03/2026 +ai-usage: ai-assisted +--- +# ZipArchive.CreateAsync eagerly loads ZIP archive entries + + now eagerly loads all ZIP archive entries during the method call. This change ensures that accessing the property doesn't perform synchronous reads on the underlying stream, which aligns with asynchronous programming patterns. + +## Version introduced + +.NET 11 Preview 1 + +## Previous behavior + +Previously, when you created a `ZipArchive` using `CreateAsync`, accessing the `Entries` property could result in synchronous (blocking) read operations being performed on the underlying stream. This behavior was inconsistent with the asynchronous nature of the `CreateAsync` method and could cause issues with streams that don't support synchronous reads. + +```csharp +using System.IO; +using System.IO.Compression; + +using var stream = new FileStream("archive.zip", FileMode.Open); +using var archive = await ZipArchive.CreateAsync(stream, ZipArchiveMode.Read); + +// This call performs synchronous reads on the stream. +// Might throw if the file entries are malformed +// or if the stream doesn't support synchronous reads. +var entries = archive.Entries; +``` + +## New behavior + +Starting in .NET 11, the central directory of the ZIP archive is read asynchronously as part of the `ZipArchive.CreateAsync` method call. Any exceptions related to malformed entries or issues reading the central directory are now thrown during the `CreateAsync` call. Subsequent access to the `Entries` property doesn't perform any read operations on the underlying stream. + +```csharp +using System.IO; +using System.IO.Compression; + +using var stream = new FileStream("archive.zip", FileMode.Open); + +// This call eagerly loads the ZIP archive entries. +// Any exceptions related to malformed entries are surfaced here. +using var archive = await ZipArchive.CreateAsync(stream, ZipArchiveMode.Read); + +// Accessing Entries no longer performs stream read operations. +var entries = archive.Entries; +``` + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was made to improve consistency and reliability when working with asynchronous streams. By eagerly loading entries during the `CreateAsync` call, the API avoids unexpected synchronous read operations later. Avoiding synchronous reads is especially important for streams that might end up blocking until data are available (such as network streams). This aligns with the approved API design and provides a more predictable programming experience. + +For more information, see [dotnet/runtime#121938](https://github.com/dotnet/runtime/pull/121938), [dotnet/runtime#121624](https://github.com/dotnet/runtime/issues/121624), and the [API design discussion](https://github.com/dotnet/runtime/issues/1541#issuecomment-2715269236). + +## Recommended action + +If your code uses `ZipArchive.CreateAsync`, ensure that you handle exceptions from the `CreateAsync` method call. This exception could already be thrown in previous .NET versions (for example, when the ZIP central directory can't be found), but now it's also thrown for malformed entries that were previously only discovered when accessing the `Entries` property. + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/sdk/11/mono-launch-target-removed.md b/docs/core/compatibility/sdk/11/mono-launch-target-removed.md new file mode 100644 index 0000000000000..043e91a60a05d --- /dev/null +++ b/docs/core/compatibility/sdk/11/mono-launch-target-removed.md @@ -0,0 +1,47 @@ +--- +title: "Breaking change: mono launch target not set for .NET Framework apps" +description: "Learn about the breaking change in .NET 11 where the .NET SDK no longer automatically sets mono as the launch target for .NET Framework applications on Linux." +ms.date: 02/03/2026 +ai-usage: ai-assisted +--- + +# mono launch target not set for .NET Framework apps + +The .NET SDK no longer automatically sets `mono` as the launch target for .NET Framework applications on Linux when using `dotnet run`. + +## Version introduced + +.NET 11 Preview 1 + +## Previous behavior + +Previously, when you called `dotnet run` on a .NET Framework application on Linux, the SDK automatically set the `RunCommand` and `RunArguments` properties in the project file to use Mono as the runtime: + +```xml +mono +"$(TargetPath)" $(StartArguments) +``` + +This allowed .NET Framework applications to be launched directly using `dotnet run` without additional configuration. + +## New behavior + +Starting in .NET 11, the SDK no longer automatically configures these properties. Running `dotnet run` on a .NET Framework application on Linux fails unless the `RunCommand` and `RunArguments` properties are explicitly set in the project file. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was made because running .NET Framework applications on Linux using Mono is no longer officially supported. Mono ownership has transitioned, and the .NET SDK should not automatically configure launch targets for unsupported scenarios. + +For more information, see [dotnet/sdk PR #52091](https://github.com/dotnet/sdk/pull/52091). + +## Recommended action + +If you need to continue running .NET Framework applications on Linux using Mono, you can manually configure the `RunCommand` and `RunArguments` properties in your project file. + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 81c34f1b2b5c8..060aa02d24c20 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -18,6 +18,8 @@ items: href: core-libraries/11/memorystream-max-capacity.md - name: TAR-reading APIs verify header checksums when reading href: core-libraries/11/tar-checksum-validation.md + - name: ZipArchive.CreateAsync eagerly loads ZIP archive entries + href: core-libraries/11/ziparchive-createasync-eager-load.md - name: Cryptography items: - name: DSA removed from macOS @@ -30,6 +32,10 @@ items: items: - name: Minimum hardware requirements updated href: jit/11/minimum-hardware-requirements.md + - name: SDK and MSBuild + items: + - name: mono launch target not set for .NET Framework apps + href: sdk/11/mono-launch-target-removed.md - name: .NET 10 items: - name: Overview diff --git a/docs/core/extensions/generic-host.md b/docs/core/extensions/generic-host.md index 977941365ac60..278bece06129a 100644 --- a/docs/core/extensions/generic-host.md +++ b/docs/core/extensions/generic-host.md @@ -1,7 +1,8 @@ --- title: .NET Generic Host description: Learn about the .NET Generic Host, which is responsible for app startup and lifetime management. -ms.date: 09/11/2024 +ms.date: 02/04/2026 +ai-usage: ai-assisted --- # .NET Generic Host @@ -20,6 +21,16 @@ When a host starts, it calls (`Host.CreateApplicationBuilder`): Introduced in .NET 6, this approach uses a linear, property-based configuration style. Services, configuration, and logging are configured by directly accessing properties on the builder object (for example, `builder.Services`, `builder.Configuration`). This approach is recommended for new projects and is the default in current .NET templates. + +- (`Host.CreateDefaultBuilder`): This is the traditional callback-based approach where configuration is done through chained extension methods (for example, `ConfigureServices`, `ConfigureAppConfiguration`). While fully supported, this legacy approach works best for maintaining compatibility with existing codebases. + +Both approaches provide the same core functionality and default behaviors. Choose `IHostApplicationBuilder` for new projects to align with modern .NET patterns and simpler configuration code. Use `IHostBuilder` when maintaining existing applications or when third-party libraries require the callback-based pattern. + ## Set up a host The host is typically configured, built, and run by code in the `Program` class. The `Main` method: diff --git a/docs/core/testing/mstest-analyzers/mstest0001.md b/docs/core/testing/mstest-analyzers/mstest0001.md index 9504634516c76..e9ce2f8201b44 100644 --- a/docs/core/testing/mstest-analyzers/mstest0001.md +++ b/docs/core/testing/mstest-analyzers/mstest0001.md @@ -23,7 +23,7 @@ dev_langs: | **Category** | Performance | | **Fix is breaking or non-breaking** | Non-breaking | | **Enabled by default** | Yes | -| **Default severity** | Warning starting with 4.0.0, Info before | +| **Default severity** | Info (Warning in 4.0) | | **Introduced in version** | 3.2.0 | | **Is there a code fix** | No | diff --git a/docs/core/testing/mstest-analyzers/mstest0023.md b/docs/core/testing/mstest-analyzers/mstest0023.md index 17946ff5c995c..f5b309014fd9b 100644 --- a/docs/core/testing/mstest-analyzers/mstest0023.md +++ b/docs/core/testing/mstest-analyzers/mstest0023.md @@ -20,7 +20,7 @@ ms.author: amauryleve | **Category** | Usage | | **Fix is breaking or non-breaking** | Non-breaking | | **Enabled by default** | Yes | -| **Default severity** | Warning starting with 4.0.0, Info before | +| **Default severity** | Info (Warning in 4.0) | | **Introduced in version** | 3.4.0 | | **Is there a code fix** | No | diff --git a/docs/core/testing/mstest-analyzers/mstest0037.md b/docs/core/testing/mstest-analyzers/mstest0037.md index a677a84a72f6d..c2e208597f843 100644 --- a/docs/core/testing/mstest-analyzers/mstest0037.md +++ b/docs/core/testing/mstest-analyzers/mstest0037.md @@ -13,16 +13,16 @@ ms.author: ygerges --- # MSTEST0037: Use proper 'Assert' methods -| Property | Value | -|-------------------------------------|------------------------------------------------------------------------| -| **Rule ID** | MSTEST0037 | -| **Title** | Use proper 'Assert' methods | -| **Category** | Usage | -| **Fix is breaking or non-breaking** | Non-breaking | -| **Enabled by default** | Yes | -| **Default severity** | Warning starting with 4.0.0, Info before | -| **Introduced in version** | 3.7.0 | -| **Is there a code fix** | Yes | +| Property | Value | +|-------------------------------------|------------------------------| +| **Rule ID** | MSTEST0037 | +| **Title** | Use proper 'Assert' methods | +| **Category** | Usage | +| **Fix is breaking or non-breaking** | Non-breaking | +| **Enabled by default** | Yes | +| **Default severity** | Info (Warning in 4.0) | +| **Introduced in version** | 3.7.0 | +| **Is there a code fix** | Yes | ## Cause diff --git a/docs/core/testing/mstest-analyzers/mstest0045.md b/docs/core/testing/mstest-analyzers/mstest0045.md index bdc4cd8e65a8b..3c2f6b47ca4fb 100644 --- a/docs/core/testing/mstest-analyzers/mstest0045.md +++ b/docs/core/testing/mstest-analyzers/mstest0045.md @@ -20,7 +20,7 @@ ms.author: amauryleve | **Category** | Usage | | **Fix is breaking or non-breaking** | Non-breaking | | **Enabled by default** | Yes | -| **Default severity** | Warning starting with 4.0.0, Info before | +| **Default severity** | Info (Warning in 4.0) | | **Introduced in version** | 3.10.0 | | **Is there a code fix** | Yes | diff --git a/docs/core/testing/mstest-analyzers/mstest0062.md b/docs/core/testing/mstest-analyzers/mstest0062.md index 9d29709fe764b..760e4a2ba9f5f 100644 --- a/docs/core/testing/mstest-analyzers/mstest0062.md +++ b/docs/core/testing/mstest-analyzers/mstest0062.md @@ -19,11 +19,11 @@ dev_langs: | Property | Value | |-------------------------------------|----------------------------------------------------| | **Rule ID** | MSTEST0062 | -| **Title** | Avoid out and ref parameters in test methods | +| **Title** | Avoid out and ref parameters in test methods | | **Category** | Usage | | **Fix is breaking or non-breaking** | Non-breaking | | **Enabled by default** | Yes | -| **Default severity** | Info | +| **Default severity** | Warning | | **Introduced in version** | 4.1.0 | | **Is there a code fix** | Yes | diff --git a/docs/core/testing/mstest-analyzers/mstest0063.md b/docs/core/testing/mstest-analyzers/mstest0063.md new file mode 100644 index 0000000000000..94c0ea563c395 --- /dev/null +++ b/docs/core/testing/mstest-analyzers/mstest0063.md @@ -0,0 +1,174 @@ +--- +title: "MSTEST0063: Test classes should have valid constructors" +description: "Learn about code analysis rule MSTEST0063: Test classes should have valid constructors" +ms.date: 02/04/2026 +f1_keywords: +- MSTEST0063 +- TestClassConstructorShouldBeValidAnalyzer +helpviewer_keywords: +- TestClassConstructorShouldBeValidAnalyzer +- MSTEST0063 +author: evangelink +ms.author: amauryleve +ai-usage: ai-assisted +dev_langs: +- CSharp +--- +# MSTEST0063: Test classes should have valid constructors + +| Property | Value | +|-------------------------------------|----------------------------------------------------| +| **Rule ID** | MSTEST0063 | +| **Title** | Test classes should have valid constructors | +| **Category** | Usage | +| **Fix is breaking or non-breaking** | Non-breaking | +| **Enabled by default** | Yes | +| **Default severity** | Warning | +| **Introduced in version** | 4.1.0 | +| **Is there a code fix** | No | + +## Cause + +A test class doesn't have a valid constructor. Valid constructors are `public` and either parameterless or have a single parameter of type . + +## Rule description + +Test classes must have a public constructor that is either parameterless or accepts a single parameter. This allows the test framework to instantiate the test class properly. + +Constructors that are non-public, have parameters of unsupported types, or have multiple parameters aren't valid and prevent the test framework from creating instances of the test class. + +```csharp +[TestClass] +public class MyTestClass +{ + private MyTestClass() // Violation - constructor is not public + { + } +} +``` + +```csharp +[TestClass] +public class MyTestClass +{ + public MyTestClass(string value) // Violation - parameter type is not supported + { + } +} +``` + +```csharp +[TestClass] +public class MyTestClass +{ + public MyTestClass(TestContext testContext, int value) // Violation - multiple parameters + { + } +} +``` + +## How to fix violations + +Ensure your test class has a valid constructor. A valid constructor must be: + +1. Declared as `public`. +1. Either parameterless or accepts a single parameter. + +### Parameterless constructor + +```csharp +[TestClass] +public class MyTestClass +{ + public MyTestClass() + { + } + + [TestMethod] + public void TestMethod() + { + } +} +``` + +### Constructor with TestContext + +```csharp +[TestClass] +public class MyTestClass +{ + private readonly TestContext _testContext; + + public MyTestClass(TestContext testContext) + { + _testContext = testContext; + } + + [TestMethod] + public void TestMethod() + { + _testContext.WriteLine("Test is running..."); + } +} +``` + +### Implicit parameterless constructor + +If you don't define any constructor, the compiler generates a public parameterless constructor automatically: + +```csharp +[TestClass] +public class MyTestClass +{ + [TestMethod] + public void TestMethod() + { + } +} +``` + +### Valid and invalid constructors together + +If your test class has multiple constructors, at least one must be valid: + +```csharp +[TestClass] +public class MyTestClass +{ + public MyTestClass() // Valid - this makes the class valid + { + } + + private MyTestClass(int x) // Invalid, but ignored because a valid constructor exists + { + } + + [TestMethod] + public void TestMethod() + { + } +} +``` + +## When to suppress warnings + +Don't suppress warnings from this rule. Test classes without valid constructors can't be instantiated by the test framework, and the tests won't run. + +## Suppress a warning + +If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule. + +```csharp +#pragma warning disable MSTEST0063 +// The code that's violating the rule is on this line. +#pragma warning restore MSTEST0063 +``` + +To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../../../fundamentals/code-analysis/configuration-files.md). + +```ini +[*.{cs,vb}] +dotnet_diagnostic.MSTEST0063.severity = none +``` + +For more information, see [How to suppress code analysis warnings](../../../fundamentals/code-analysis/suppress-warnings.md). diff --git a/docs/core/testing/mstest-analyzers/overview.md b/docs/core/testing/mstest-analyzers/overview.md index 1c605f3f21ef1..54d6122b2fd9b 100644 --- a/docs/core/testing/mstest-analyzers/overview.md +++ b/docs/core/testing/mstest-analyzers/overview.md @@ -111,6 +111,7 @@ Rules that help ensure your test classes and methods are properly structured and - [MSTEST0056](mstest0056.md) - TestMethodAttribute should set DisplayName correctly - [MSTEST0057](mstest0057.md) - TestMethodAttribute should propagate source information - [MSTEST0060](mstest0060.md) - Duplicate TestMethodAttribute +- [MSTEST0063](mstest0063.md) - Test class should have valid constructor Related documentation: [Write tests with MSTest](../unit-testing-mstest-writing-tests.md), [Attributes](../unit-testing-mstest-writing-tests-attributes.md) @@ -276,6 +277,7 @@ Related documentation: [Configure MSTest](../unit-testing-mstest-configure.md), | [MSTEST0060](mstest0060.md) | Usage | Duplicate TestMethodAttribute | Warning | | [MSTEST0061](mstest0061.md) | Usage | Use OSCondition attribute instead of runtime check | Info | | [MSTEST0062](mstest0062.md) | Usage | Avoid out/ref test method parameters | Warning | +| [MSTEST0063](mstest0063.md) | Usage | Test class should have valid constructor | Warning | \* Escalated to Error in `Recommended` and `All` modes. diff --git a/docs/core/testing/mstest-analyzers/usage-rules.md b/docs/core/testing/mstest-analyzers/usage-rules.md index 393f5b9583a5d..bec20f80ef053 100644 --- a/docs/core/testing/mstest-analyzers/usage-rules.md +++ b/docs/core/testing/mstest-analyzers/usage-rules.md @@ -58,6 +58,7 @@ Usage rules support proper usage of MSTest attributes, methods, and patterns. Th | [MSTEST0060](mstest0060.md) | Duplicate TestMethodAttribute. | Warning | Yes | | [MSTEST0061](mstest0061.md) | Use OSCondition attribute instead of runtime check. | Info | Yes | | [MSTEST0062](mstest0062.md) | Avoid out/ref test method parameters. | Warning | Yes | +| [MSTEST0063](mstest0063.md) | Test class should have valid constructor. | Warning | No | \* Escalated to Error in `Recommended` and `All` modes. @@ -70,6 +71,7 @@ Ensure your test classes, methods, and fixtures follow MSTest requirements: - **[MSTEST0002](mstest0002.md)**: Test class layout requirements (for example, public, non-static). - **[MSTEST0003](mstest0003.md)**: Test method layout requirements (⚠️ escalated to Error). - **[MSTEST0030](mstest0030.md)**: Methods with [TestMethod] must be in a [TestClass]. +- **[MSTEST0063](mstest0063.md)**: Test class constructor validation. ### Lifecycle methods diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index f3527cf95946c..5b01d3f22d76d 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -202,6 +202,11 @@ For more information, see the following resources: Publishes the application for a given runtime. For a list of Runtime Identifiers (RIDs), see the [RID catalog](../rid-catalog.md). For more information, see [.NET application publishing overview](../deploying/index.md). If you use this option, use `--self-contained` or `--no-self-contained` also. + > [!NOTE] + > Publishing can be done on the *solution* level and on the single *project* level. When publishing from the *solution* level by specifying the optional `` parameter or leaving it default, MSBuild first compiles the output into the `publish` directory **without** any symbols. This means that later compilations done by MSBuild, based on the initial compilation, will still not include any details for specified ``. + > + > This is expected behavior. To avoid this behavior either publish for a single project by specifying the optional `` parameter for your RID or specify RIDs directly in the project config by adding the [``](../project-sdk/msbuild-props.md#runtimeidentifiers) property. + - [!INCLUDE [tl](includes/cli-tl.md)] - [!INCLUDE [use-current-runtime](includes/cli-use-current-runtime.md)] diff --git a/docs/core/tools/dotnet-test-mtp.md b/docs/core/tools/dotnet-test-mtp.md index c349763cc2d77..64fd7f0d22f0c 100644 --- a/docs/core/tools/dotnet-test-mtp.md +++ b/docs/core/tools/dotnet-test-mtp.md @@ -1,7 +1,7 @@ --- title: dotnet test command with Microsoft.Testing.Platform description: The dotnet test command is used to execute unit tests in a given project using Microsoft.Testing.Platform (MTP). -ms.date: 12/29/2024 +ms.date: 02/03/2026 ai-usage: ai-assisted --- # dotnet test with Microsoft.Testing.Platform (MTP) @@ -21,6 +21,10 @@ dotnet test [--test-modules ] [--root-directory ] [--max-parallel-test-modules ] + [--config-file ] + [--results-directory ] + [--diagnostic-output-directory ] + [--minimum-expected-tests ] [-a|--arch ] [-c|--configuration ] [-f|--framework ] @@ -76,6 +80,22 @@ With Microsoft Testing Platform, `dotnet test` operates faster than with VSTest. Specifies the maximum number of test modules that can run in parallel. The default is . +- **`--config-file `** + + Specifies the configuration file to use for test execution. If a relative path is provided, it's converted to an absolute path based on the current directory. For more information about the configuration file settings, see [testconfig.json](../testing/microsoft-testing-platform-config.md#testconfigjson). + +- **`--results-directory `** + + Specifies the directory where test results are stored. If the directory doesn't exist, it's created. If a relative path is provided, it's converted to an absolute path based on the current directory. + +- **`--diagnostic-output-directory `** + + Specifies the directory where diagnostic output is stored. If the directory doesn't exist, it's created. If a relative path is provided, it's converted to an absolute path based on the current directory. + +- **`--minimum-expected-tests `** + + Specifies the minimum number of tests that must be executed. If the actual number of tests is less than the specified minimum, the test run fails with exit code 9. For more information about exit codes, see [Microsoft.Testing.Platform exit codes](../testing/microsoft-testing-platform-exit-codes.md). + - [!INCLUDE [arch](includes/cli-arch.md)] - [!INCLUDE [configuration](includes/cli-configuration.md)] @@ -186,6 +206,24 @@ With Microsoft Testing Platform, `dotnet test` operates faster than with VSTest. dotnet test --coverage ``` +- Run the tests and store results in a specific directory: + + ```dotnetcli + dotnet test --results-directory ./TestResults + ``` + +- Run the tests with diagnostic output in a specific directory: + + ```dotnetcli + dotnet test --diagnostic-output-directory ./Diagnostics + ``` + +- Run the tests ensuring at least 10 tests are executed: + + ```dotnetcli + dotnet test --minimum-expected-tests 10 + ``` + - Run the tests in the `TestProject` project, providing the `-bl` (binary log) argument to `msbuild`: ```dotnetcli diff --git a/docs/core/tutorials/debugging-with-visual-studio-code.md b/docs/core/tutorials/debugging-with-visual-studio-code.md index 5c5d712a4faa7..7d9488f747f45 100644 --- a/docs/core/tutorials/debugging-with-visual-studio-code.md +++ b/docs/core/tutorials/debugging-with-visual-studio-code.md @@ -1,51 +1,76 @@ --- title: Debug a .NET console application using Visual Studio Code description: Learn how to debug a .NET console app using Visual Studio Code. -ms.date: 10/23/2025 +ms.date: 01/27/2026 +zone_pivot_groups: code-editor-set-one --- # Tutorial: Debug a .NET console application using Visual Studio Code +::: zone pivot="vscode" + This tutorial introduces the debugging tools available in Visual Studio Code for working with .NET apps. +::: zone-end + +::: zone pivot="codespaces" + +This tutorial introduces the debugging tools available in GitHub Codespaces for working with .NET apps. + +::: zone-end + ## Prerequisites This tutorial works with the console app that you create in [Create a .NET console application using Visual Studio Code](with-visual-studio-code.md). -## Use Debug build configuration - -*Debug* and *Release* are .NET's built-in build configurations. You use the Debug build configuration for debugging and the Release configuration for the final release distribution. +## Set a breakpoint -In the Debug configuration, a program compiles with full symbolic debug information and no optimization. Optimization complicates debugging, because the relationship between source code and generated instructions is more complex. The release configuration of a program has no symbolic debug information and is fully optimized. +A *breakpoint* temporarily interrupts the execution of the application before the line with the breakpoint is run. -By default, Visual Studio Code launch settings use the Debug build configuration, so you don't need to change it before debugging. +::: zone pivot="vscode" 1. Start Visual Studio Code. 1. Open the folder of the project that you created in [Create a .NET console application using Visual Studio Code](with-visual-studio-code.md). -## Set a breakpoint - -A *breakpoint* temporarily interrupts the execution of the application before the line with the breakpoint is run. - 1. Open the *Program.cs* file. 1. Set a *breakpoint* on the line that displays the name, date, and time, by clicking in the left margin of the code window. The left margin is to the left of the line numbers. Other ways to set a breakpoint are by pressing F9 or choosing **Run** > **Toggle Breakpoint** from the menu while the line of code is selected. Visual Studio Code indicates the line on which the breakpoint is set by displaying a red dot in the left margin. - :::image type="content" source="media/debugging-with-visual-studio-code/breakpoint-set-net6.png" alt-text="Breakpoint set"::: + :::image type="content" source="media/debugging-with-visual-studio-code/breakpoint-set.png" alt-text="Breakpoint set"::: + +::: zone-end + +::: zone pivot="codespaces" + +1. Open your GitHub Codespace that you created in [Create a .NET console application using Visual Studio Code](with-visual-studio-code.md). + +1. Open the *HelloWorld.cs* file. + +1. Set a *breakpoint* on the line that displays the name, date, and time, by clicking in the left margin of the code window. The left margin is to the left of the line numbers. You can also set a breakpoint are by pressing F9 while the line of code is selected. + + :::image type="content" source="media/debugging-with-visual-studio-code/codespaces-breakpoint-set.png" alt-text="Breakpoint set"::: + +::: zone-end ## Start debugging +*Debug* and *Release* are .NET's built-in build configurations. You use the Debug build configuration for debugging and the Release configuration for the final release distribution. + +::: zone pivot="vscode" + +By default, Visual Studio Code launch settings use the Debug build configuration, so you don't need to change it before debugging. + 1. Open the Debug view by selecting the Debugging icon on the left side menu. - :::image type="content" source="media/debugging-with-visual-studio-code/select-debug-pane-net6.png" alt-text="Open the Debug tab in Visual Studio Code"::: + :::image type="content" source="media/debugging-with-visual-studio-code/select-debug-pane.png" alt-text="Open the Debug tab in Visual Studio Code"::: 1. Select **Run and Debug**. If asked, select **C#** and then select **C#: Launch startup project**. Other ways to start the program in debugging mode are by pressing F5 or choosing **Run** > **Start Debugging** from the menu. :::image type="content" source="media/debugging-with-visual-studio-code/start-debugging.png" alt-text="Start debugging"::: -1. If asked to **Select Launch Configuration**, select **C#: HelloWorld HelloWorld**. +1. If asked to **Select Launch Configuration**, select **C#: Debug Active File**. 1. Select the **Debug Console** tab to see the "What is your name?" prompt that the program displays before waiting for a response. @@ -55,7 +80,29 @@ A *breakpoint* temporarily interrupts the execution of the application before th Program execution stops when it reaches the breakpoint and before the `Console.WriteLine` method runs. The **Locals** section of the **Variables** window displays the values of variables that are defined in the currently running method. - :::image type="content" source="media/debugging-with-visual-studio-code/breakpoint-hit-net6.png" alt-text="Breakpoint hit, showing Locals"::: + :::image type="content" source="media/debugging-with-visual-studio-code/breakpoint-hit.png" alt-text="Breakpoint hit, showing Locals"::: + +::: zone-end + +::: zone pivot="codespaces" + +By default, GitHub Codespaces uses the Debug build configuration, so you don't need to change it before debugging. + +1. Open the Debug view by selecting the Debugging icon on the left side menu. + + :::image type="content" source="media/debugging-with-visual-studio-code/codespaces-select-debug-pane.png" alt-text="Open the Debug tab in Visual Studio Code"::: + +1. Select **Run and Debug**. If asked, select **C#** as the debugger and then select **C#: Debug Active File** as the Launch Configuration. + +1. Select the **Debug Console** tab to see the "What is your name?" prompt that the program displays before waiting for a response. + +1. Enter a string in the **Debug Console** window in response to the prompt for a name, and then press Enter. + + Program execution stops when it reaches the breakpoint and before the `Console.WriteLine` method runs. The **Locals** section of the **Variables** window displays the values of variables that are defined in the currently running method. + + :::image type="content" source="media/debugging-with-visual-studio-code/codespaces-breakpoint-hit.png" alt-text="Breakpoint hit, showing Locals"::: + +::: zone-end ## Use the Debug Console @@ -65,9 +112,9 @@ The **Debug Console** window lets you interact with the application you're debug 1. Enter `name = "Gracie"` at the prompt at the bottom of the **Debug Console** window and press Enter. - :::image type="content" source="media/debugging-with-visual-studio-code/change-variable-values-net6.png" alt-text="Change variable values"::: + :::image type="content" source="media/debugging-with-visual-studio-code/change-variable-values.png" alt-text="Change variable values"::: -1. Enter `currentDate = DateTime.Parse("2019-11-16T17:25:00Z").ToUniversalTime()` at the bottom of the **Debug Console** window and press Enter. +1. Enter `currentDate = DateTime.Parse("2026-01-28T20:54:00Z").ToUniversalTime()` at the bottom of the **Debug Console** window and press Enter. The **Variables** window displays the new values of the `name` and `currentDate` variables. @@ -77,7 +124,7 @@ The **Debug Console** window lets you interact with the application you're debug The values displayed in the console window correspond to the changes you made in the **Debug Console**. - :::image type="content" source="media/debugging-with-visual-studio-code/changed-variable-values.png" alt-text="Terminal showing the entered values"::: + :::image type="content" source="media/debugging-with-visual-studio-code/codespaces-changed-variable-values.png" alt-text="Terminal showing the entered values"::: 1. Press Enter to exit the application and stop debugging. @@ -87,7 +134,7 @@ The program displays the string that the user enters. What happens if the user d 1. Right-click (Ctrl-click on macOS) on the red dot that represents the breakpoint. In the context menu, select **Edit Breakpoint** to open a dialog that lets you enter a conditional expression. - :::image type="content" source="media/debugging-with-visual-studio-code/breakpoint-context-menu-net6.png" alt-text="Breakpoint context menu"::: + :::image type="content" source="media/debugging-with-visual-studio-code/breakpoint-context-menu.png" alt-text="Breakpoint context menu"::: 1. Select `Expression` in the drop-down, enter the following conditional expression, and press Enter. @@ -95,7 +142,7 @@ The program displays the string that the user enters. What happens if the user d String.IsNullOrEmpty(name) ``` - :::image type="content" source="media/debugging-with-visual-studio-code/conditional-expression-net6.png" alt-text="Enter a conditional expression"::: + :::image type="content" source="media/debugging-with-visual-studio-code/conditional-expression.png" alt-text="Enter a conditional expression"::: Each time the breakpoint is hit, the debugger calls the `String.IsNullOrEmpty(name)` method, and it breaks on this line only if the method call returns `true`. @@ -127,7 +174,7 @@ The program displays the string that the user enters. What happens if the user d Visual Studio Code also allows you to step line by line through a program and monitor its execution. Ordinarily, you'd set a breakpoint and follow program flow through a small part of your program code. Since this program is small, you can step through the entire program. -1. Set a breakpoint on the opening curly brace of the `Main` method. +1. Set a breakpoint on the line of code that displays the "What is your name?" prompt. 1. Press F5 to start debugging. @@ -135,37 +182,35 @@ Visual Studio Code also allows you to step line by line through a program and mo At this point, the **Variables** window shows that the `args` array is empty, and `name` and `currentDate` have default values. -1. Select **Run** > **Step Into** or press F11. +1. Select **Step Into** from the Debug toolbar or press F11. :::image type="content" source="media/debugging-with-visual-studio-code/step-into.png" alt-text="Step-Into button"::: Visual Studio Code highlights the next line. -1. Select **Run** > **Step Into** or press F11. - - Visual Studio Code runs the `Console.WriteLine` for the name prompt and highlights the next line of execution. The next line is the `Console.ReadLine` for the `name`. The **Variables** window is unchanged, and the **Terminal** tab shows the "What is your name?" prompt. +1. Visual Studio Code runs the `Console.WriteLine` for the name prompt and highlights the next line of execution. The next line is the `Console.ReadLine` for the `name`. The **Variables** window is unchanged, and the **Terminal** tab shows the "What is your name?" prompt. -1. Select **Run** > **Step Into** or press F11. +1. Select **Step Into** or press F11. - Visual Studio highlights the `name` variable assignment. The **Variables** window shows that `name` is still `null`. + Visual Studio Code highlights the `name` variable assignment. The **Variables** window shows that `name` is still `null`. 1. Respond to the prompt by entering a string in the Terminal tab and pressing Enter. The **Debug Console** tab might not display the string you enter while you're entering it, but the method will capture your input. -1. Select **Run** > **Step Into** or press F11. +1. Select **Step Into** or press F11. Visual Studio Code highlights the `currentDate` variable assignment. The **Variables** window shows the value returned by the call to the method. The **Terminal** tab displays the string you entered at the prompt. -1. Select **Run** > **Step Into** or press F11. +1. Select **Step Into** or press F11. The **Variables** window shows the value of the `currentDate` variable after the assignment from the property. -1. Select **Run** > **Step Into** or press F11. +1. Select **Step Into** or press F11. Visual Studio Code calls the method. The console window displays the formatted string. -1. Select **Run** > **Step Out** or press Shift+F11. +1. Select **Step Out** or press Shift+F11. :::image type="content" source="media/debugging-with-visual-studio-code/step-out.png" alt-text="Step-Out button"::: @@ -177,15 +222,25 @@ Visual Studio Code also allows you to step line by line through a program and mo Once you've tested the Debug version of your application, you should also compile and test the Release version. The Release version incorporates compiler optimizations that can affect the behavior of an application. For example, compiler optimizations that are designed to improve performance can create race conditions in multithreaded applications. +::: zone pivot="vscode" + To build and test the Release version of your console application, open the **Terminal** and run the following command: ```dotnetcli dotnet run --configuration Release ``` -## Additional resources +::: zone-end + +::: zone pivot="codespaces" + +To build and test the Release version of your console application, run the following command in the terminal: + +```dotnetcli +dotnet run --configuration Release HelloWorld.cs +``` -- [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) +::: zone-end ## Next steps diff --git a/docs/core/tutorials/library-with-visual-studio-code.md b/docs/core/tutorials/library-with-visual-studio-code.md index 27956ba613de4..fbb8b06e9f8a3 100644 --- a/docs/core/tutorials/library-with-visual-studio-code.md +++ b/docs/core/tutorials/library-with-visual-studio-code.md @@ -1,13 +1,13 @@ --- title: Create a .NET class library using Visual Studio Code description: Learn how to create a .NET class library using Visual Studio Code. -ms.date: 09/12/2024 +ms.date: 01/29/2026 --- # Tutorial: Create a .NET class library using Visual Studio Code In this tutorial, you create a simple utility library that contains a single string-handling method. -A *class library* defines types and methods that are called by an application. If the library targets .NET Standard 2.0, it can be called by any .NET implementation (including .NET Framework) that supports .NET Standard 2.0. If the library targets .NET 9, it can be called by any application that targets .NET 9. This tutorial shows how to target .NET 9. +A *class library* defines types and methods that are called by an application. If the library targets .NET Standard 2.0, it can be called by any .NET implementation (including .NET Framework) that supports .NET Standard 2.0. If the library targets .NET 10, it can be called by any application that targets .NET 10. This tutorial shows how to target .NET 10. When you create a class library, you can distribute it as a third-party component or as a bundled component with one or more applications. @@ -23,33 +23,23 @@ Start by creating a .NET class library project named "StringLibrary" and an asso 1. Go to the Explorer view and select **Create .NET Project**. Alternatively, you can bring up the Command Palette using Ctrl+Shift+P (Command+Shift+P on MacOS) and then type ".NET" and find and select the .NET: New Project command. -1. After selecting the command, you'll need to choose the project template. Choose Class Library. - -1. Then select the location where you would like the new project to be created. +1. Choose the project template **Class Library**. 1. Then select the location where you would like the new project to be created: Create a folder named `ClassLibraryProjects` and select it. -1. Name the project **StringLibrary**, select **Show all template options**, select **.NET 9** and select **Create Project**. - -1. Name the project **StringLibrary** and select **Create Project**. +1. Name the project **StringLibrary**. -1. Press Enter at the prompt **Project will be created in \**. +1. Select **.sln** as the solution file format. -1. Check to make sure that the library targets .NET 9. In **Explorer**, open *StringLibrary/StringLibrary.csproj*. +1. Select **Show all template options**. - The `TargetFramework` element shows that the project targets .NET 9.0. +1. Next select **.NET 10**. Then select **Create Project**. - ```xml - +1. In the **Do you trust the authors of the files in this folder?** dialog, select **Yes, I trust the authors**. You can trust the authors because this folder only has files generated by .NET and added or modified by you. - - net9.0 - +1. The project is created and *Class1.cs* opens. - - ``` - -1. Open *Class1.cs* and replace the code with the following code. +1. Replace the contents of *Class1.cs* with the following code: :::code language="csharp" source="./snippets/library-with-visual-studio/csharp/StringLibrary/Class1.cs"::: @@ -66,11 +56,9 @@ Start by creating a .NET class library project named "StringLibrary" and an asso The terminal output looks like the following example: ```output - Microsoft (R) Build Engine version 17.8.0+b89cb5fde for .NET - Copyright (C) Microsoft Corporation. All rights reserved. Determining projects to restore... All projects are up-to-date for restore. - StringLibrary -> C:\Projects\ClassLibraryProjects\StringLibrary\bin\Debug\net9.0\StringLibrary.dll + StringLibrary -> C:\Projects\ClassLibraryProjects\StringLibrary\bin\Debug\net10.0\StringLibrary.dll Build succeeded. 0 Warning(s) 0 Error(s) @@ -83,9 +71,9 @@ Add a console application that uses the class library. The app will prompt the u 1. Right-click the solution in **Solution Explorer** and select **New Project**, or in the Command Palette select **.NET: New Project**. -1. Select Console app. +1. Select **Console App**. -1. Give it the name **ShowCase**, select the default location and select **Create Project**. +1. Give it the name **ShowCase**, select the default directory and select **Create Project**. 1. Open *ShowCase/Program.cs* and replace all of the code with the following code. @@ -105,13 +93,22 @@ Initially, the new console app project doesn't have access to the class library. 1. Select StringLibrary. +> [!TIP] +> Alternatively, add the following to *ShowCase.csproj*: +> +> ```xml +> +> +> +> ``` + ## Run the app -1. Select **Run** > **Run without debugging**. +1. Use the top menu bar to select **Run** > **Run without debugging**. 1. Select **C#**. -1. Select **ShowCase**. +1. Select **C#: ShowCase**. If you get an error that says no C# program is loaded, close the folder that you have open, and open the `ShowCase` folder. Then try running the app again. diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-context-menu-net6.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-context-menu-net6.png deleted file mode 100644 index 47c21bcae2703..0000000000000 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-context-menu-net6.png and /dev/null differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-context-menu.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-context-menu.png new file mode 100644 index 0000000000000..5fb854b7c144c Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-context-menu.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-hit-net6.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-hit-net6.png deleted file mode 100644 index cb706229ee9e1..0000000000000 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-hit-net6.png and /dev/null differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-hit.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-hit.png new file mode 100644 index 0000000000000..74249ba9c5e54 Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-hit.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-set-net6.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-set-net6.png deleted file mode 100644 index 4108b03c8d447..0000000000000 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-set-net6.png and /dev/null differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-set.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-set.png new file mode 100644 index 0000000000000..af38cdbf2041c Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/breakpoint-set.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/change-variable-values-net6.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/change-variable-values-net6.png deleted file mode 100644 index cce287c861176..0000000000000 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/change-variable-values-net6.png and /dev/null differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/change-variable-values.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/change-variable-values.png new file mode 100644 index 0000000000000..52210a3fe29d6 Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/change-variable-values.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-breakpoint-hit.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-breakpoint-hit.png new file mode 100644 index 0000000000000..405bcd48258a9 Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-breakpoint-hit.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-breakpoint-set.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-breakpoint-set.png new file mode 100644 index 0000000000000..2bd133bf5c058 Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-breakpoint-set.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-changed-variable-values.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-changed-variable-values.png new file mode 100644 index 0000000000000..58f44202f6f5a Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-changed-variable-values.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-select-debug-pane.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-select-debug-pane.png new file mode 100644 index 0000000000000..9bb45d077c406 Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/codespaces-select-debug-pane.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/conditional-expression-net6.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/conditional-expression-net6.png deleted file mode 100644 index c8bf683804a08..0000000000000 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/conditional-expression-net6.png and /dev/null differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/conditional-expression.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/conditional-expression.png new file mode 100644 index 0000000000000..ac462927bd752 Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/conditional-expression.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/continue-debugging.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/continue-debugging.png index ce364de68ea2a..ec9c991207afb 100644 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/continue-debugging.png and b/docs/core/tutorials/media/debugging-with-visual-studio-code/continue-debugging.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-console.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-console.png index 0fbb26f2f429e..db0437a631bb5 100644 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-console.png and b/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-console.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-pane-net6.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-pane-net6.png deleted file mode 100644 index 081bb61db19f0..0000000000000 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-pane-net6.png and /dev/null differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-pane.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-pane.png new file mode 100644 index 0000000000000..77bddf0641c01 Binary files /dev/null and b/docs/core/tutorials/media/debugging-with-visual-studio-code/select-debug-pane.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/start-debugging.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/start-debugging.png index e7227949661b3..2ddea0e6fd5ec 100644 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/start-debugging.png and b/docs/core/tutorials/media/debugging-with-visual-studio-code/start-debugging.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/step-into.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/step-into.png index e2686ea83f1af..fc9731bc53c86 100644 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/step-into.png and b/docs/core/tutorials/media/debugging-with-visual-studio-code/step-into.png differ diff --git a/docs/core/tutorials/media/debugging-with-visual-studio-code/step-out.png b/docs/core/tutorials/media/debugging-with-visual-studio-code/step-out.png index a55550da55dde..f143d2c6c2407 100644 Binary files a/docs/core/tutorials/media/debugging-with-visual-studio-code/step-out.png and b/docs/core/tutorials/media/debugging-with-visual-studio-code/step-out.png differ diff --git a/docs/core/tutorials/media/publishing-with-visual-studio-code/codespaces-published-files-output.png b/docs/core/tutorials/media/publishing-with-visual-studio-code/codespaces-published-files-output.png new file mode 100644 index 0000000000000..c8aaaa3ecc888 Binary files /dev/null and b/docs/core/tutorials/media/publishing-with-visual-studio-code/codespaces-published-files-output.png differ diff --git a/docs/core/tutorials/media/publishing-with-visual-studio-code/published-files-output-net8.png b/docs/core/tutorials/media/publishing-with-visual-studio-code/published-files-output-net8.png deleted file mode 100644 index e5804c63d1e08..0000000000000 Binary files a/docs/core/tutorials/media/publishing-with-visual-studio-code/published-files-output-net8.png and /dev/null differ diff --git a/docs/core/tutorials/media/publishing-with-visual-studio-code/published-files-output.png b/docs/core/tutorials/media/publishing-with-visual-studio-code/published-files-output.png new file mode 100644 index 0000000000000..b84bdb191ef61 Binary files /dev/null and b/docs/core/tutorials/media/publishing-with-visual-studio-code/published-files-output.png differ diff --git a/docs/core/tutorials/media/with-visual-studio-code/codespaces-create-new-file.png b/docs/core/tutorials/media/with-visual-studio-code/codespaces-create-new-file.png new file mode 100644 index 0000000000000..638a47be64430 Binary files /dev/null and b/docs/core/tutorials/media/with-visual-studio-code/codespaces-create-new-file.png differ diff --git a/docs/core/tutorials/media/with-visual-studio-code/create-codespace-on-main.png b/docs/core/tutorials/media/with-visual-studio-code/create-codespace-on-main.png new file mode 100644 index 0000000000000..e67036208c345 Binary files /dev/null and b/docs/core/tutorials/media/with-visual-studio-code/create-codespace-on-main.png differ diff --git a/docs/core/tutorials/media/with-visual-studio-code/create-dotnet-project.png b/docs/core/tutorials/media/with-visual-studio-code/create-dotnet-project.png new file mode 100644 index 0000000000000..4095e2e46db8f Binary files /dev/null and b/docs/core/tutorials/media/with-visual-studio-code/create-dotnet-project.png differ diff --git a/docs/core/tutorials/media/with-visual-studio-code/run-program-class.png b/docs/core/tutorials/media/with-visual-studio-code/run-program-class.png new file mode 100644 index 0000000000000..047f1a0e55d4b Binary files /dev/null and b/docs/core/tutorials/media/with-visual-studio-code/run-program-class.png differ diff --git a/docs/core/tutorials/publishing-with-visual-studio-code.md b/docs/core/tutorials/publishing-with-visual-studio-code.md index 1763c8e82c5a6..884e954b9cd75 100644 --- a/docs/core/tutorials/publishing-with-visual-studio-code.md +++ b/docs/core/tutorials/publishing-with-visual-studio-code.md @@ -1,13 +1,14 @@ --- title: Publish a .NET console application using Visual Studio Code description: Learn how to use Visual Studio Code and the .NET CLI to create the set of files that are needed to run a .NET application. -ms.date: 09/12/2024 +ms.date: 01/28/2026 +zone_pivot_groups: code-editor-set-one --- # Tutorial: Publish a .NET console application using Visual Studio Code This tutorial shows how to publish a console app so that other users can run it. Publishing creates the set of files that are needed to run an application. To deploy the files, copy them to the target machine. -The .NET CLI is used to publish the app, so you can follow this tutorial with a code editor other than Visual Studio Code if you prefer. +The .NET CLI is used to publish the app. ## Prerequisites @@ -15,6 +16,8 @@ The .NET CLI is used to publish the app, so you can follow this tutorial with a ## Publish the app +::: zone pivot="vscode" + 1. Start Visual Studio Code. 1. Open the *HelloWorld* project folder that you created in [Create a .NET console application using Visual Studio Code](with-visual-studio-code.md). @@ -34,25 +37,60 @@ The .NET CLI is used to publish the app, so you can follow this tutorial with a The command output is similar to the following example: ```output - Microsoft (R) Build Engine version 17.8.0+b89cb5fde for .NET - Copyright (C) Microsoft Corporation. All rights reserved. - Determining projects to restore... - All projects are up-to-date for restore. - HelloWorld -> C:\Projects\HelloWorld\bin\Release\net8.0\HelloWorld.dll - HelloWorld -> C:\Projects\HelloWorld\bin\Release\net8.0\publish\ + Restore complete (1.1s) + HelloWorld net10.0 succeeded (7.8s) → bin\Release\net10.0\publish\ + + Build succeeded in 10.3s ``` +::: zone-end + +::: zone pivot="codespaces" + +1. Open your GitHub Codespace that you created in [Create a .NET console application using Visual Studio Code](with-visual-studio-code.md). + +1. Add the following line of code to the top of *HelloWorld.cs*: + + ```csharp + #:property PublishAot=false + ``` + + This property directive, disables native ahead-of-time (AOT) compilation and the app will use the standard just-in-time (JIT) compiler at runtime. The published output will be framework-dependent. + +1. In the terminal, make sure you're in the *tutorials* folder. + +1. Run the following command: + + ```dotnetcli + dotnet publish HelloWorld.cs + ``` + + The command creates an independent executable. + + The command output is similar to the following example: + + ```output + Restore complete (0.5s) + HelloWorld net10.0 succeeded (4.0s) → artifacts\HelloWorld\ + + Build succeeded in 5.1s + ``` + +::: zone-end + ## Inspect the files +::: zone pivot="vscode" + By default, the publishing process creates a framework-dependent deployment, which is a type of deployment where the published application runs on a machine that has the .NET runtime installed. To run the published app you can use the executable file or run the `dotnet HelloWorld.dll` command from a command prompt. In the following steps, you'll look at the files created by the publish process. 1. Select the **Explorer** in the left navigation bar. -1. Expand *bin/Release/net8.0/publish*. +1. Expand *bin/Release/net10.0/publish*. - :::image type="content" source="media/publishing-with-visual-studio-code/published-files-output-net8.png" alt-text="Explorer showing published files"::: + :::image type="content" source="media/publishing-with-visual-studio-code/published-files-output.png" alt-text="Explorer showing published files"::: As the image shows, the published output includes the following files: @@ -66,7 +104,7 @@ In the following steps, you'll look at the files created by the publish process. - *HelloWorld.exe* (*HelloWorld* on Linux or macOS.) - This is the [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) version of the application. The file is operating-system-specific. + This is the [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) version of the application. The file is operating-system-specific. - *HelloWorld.pdb* (optional for deployment) @@ -76,8 +114,50 @@ In the following steps, you'll look at the files created by the publish process. This is the application's runtime configuration file. It identifies the version of .NET that your application was built to run on. You can also add configuration options to it. For more information, see [.NET runtime configuration settings](../runtime-config/index.md#runtimeconfigjson). +::: zone-end + +::: zone pivot="codespaces" + +For a single-file application, the publishing process creates an artifacts directory with a compiled assembly file. The published application can be run using the `dotnet` command. + +In the following steps, you'll look at the files created by the publish process. + +1. Select the **Explorer** in the left navigation bar. + +1. Expand *artifacts/HelloWorld*. + + :::image type="content" source="media/publishing-with-visual-studio-code/codespaces-published-files-output.png" alt-text="Explorer showing published files"::: + + As the image shows, the published output includes the following files: + + - *HelloWorld* + + This is the [framework-dependent executable](../deploying/index.md#framework-dependent-deployment) version of the application. The file is operating-system-specific. Codespaces runs on Linux, so this a Linux executable. + + - *HelloWorld.deps.json* + + This is the application's runtime dependencies file. It defines the .NET components and the libraries (including the dynamic link library that contains your application) needed to run the app. For more information, see [Runtime configuration files](https://github.com/dotnet/cli/blob/4af56f867f2f638b4562c3b8432d70f7b09577b3/Documentation/specs/runtime-configuration-file.md). + + - *HelloWorld.dll* + + This is the [framework-dependent deployment](../deploying/index.md#cross-platform-dll-deployment) version of the application. To run this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. + + - *HelloWorld.pdb* (optional for deployment) + + This is the debug symbols file. You aren't required to deploy this file along with your application, although you should save it in the event that you need to debug the published version of your application. + + - *HelloWorld.runtimeconfig.json* + + This is the application's runtime configuration file. It identifies the version of .NET that your application was built to run on. You can also add configuration options to it. For more information, see [.NET runtime configuration settings](../runtime-config/index.md#runtimeconfigjson). + + Right-click and select **Download...** to download files from Codespaces to your local computer. + +::: zone-end + ## Run the published app +::: zone pivot="vscode" + 1. In **Explorer**, right-click the *publish* folder (Ctrl-click on macOS), and select **Open in Integrated Terminal**. :::image type="content" source="media/publishing-with-visual-studio-code/open-in-terminal.png" alt-text="Context menu showing Open in Terminal"::: @@ -96,12 +176,32 @@ In the following steps, you'll look at the files created by the publish process. 1. Enter a name in response to the prompt, and press Enter to exit. +::: zone-end + +::: zone pivot="codespaces" + +1. In **Explorer**, right-click the *artifacts/HelloWorld* folder and select **Open in Integrated Terminal**. + +1. Run the app by using the executable. Enter `./HelloWorld` and then press Enter. + +1. Enter a name in response to the prompt, and press Enter to exit. + +::: zone-end + ## Additional resources - [.NET application publishing overview](../deploying/index.md) - [`dotnet publish`](../tools/dotnet-publish.md) - [Use the .NET SDK in continuous integration (CI) environments](../../devops/dotnet-cli-and-continuous-integration.md) +::: zone pivot="codespaces" + +## Cleanup resources + +GitHub automatically deletes your Codespace after 30 days of inactivity. If you plan to explore more tutorials in this series, you can leave your Codespace provisioned. If you're ready to visit the [.NET site](https://dotnet.microsoft.com/download/dotnet) to download the .NET SDK, you can delete your Codespace. To delete your Codespace, open a browser window and navigate to [your Codespaces](https://github.com/codespaces). You see a list of your codespaces in the window. Select the three dots (`...`) in the entry for the learn tutorial codespace. Then select "delete". + +::: zone-end + ## Next steps In this tutorial, you published a console app. In the next tutorial, you create a class library. diff --git a/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibrary/StringLibrary.vbproj b/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibrary/StringLibrary.vbproj index 6eb01e27ddfa2..7b89592f88445 100644 --- a/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibrary/StringLibrary.vbproj +++ b/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibrary/StringLibrary.vbproj @@ -2,7 +2,7 @@ - netstandard2.0 + net10.0 diff --git a/docs/core/tutorials/snippets/with-visual-studio-code/csharp/HelloWorld.cs b/docs/core/tutorials/snippets/with-visual-studio-code/csharp/HelloWorld.cs new file mode 100644 index 0000000000000..5255638abec71 --- /dev/null +++ b/docs/core/tutorials/snippets/with-visual-studio-code/csharp/HelloWorld.cs @@ -0,0 +1,12 @@ +// +Console.WriteLine("Hello, World!"); +// + +// +Console.WriteLine("What is your name?"); +var name = Console.ReadLine(); +var currentDate = DateTime.Now; +Console.WriteLine($"{Environment.NewLine}Hello, {name}, on {currentDate:d} at {currentDate:t}!"); +Console.Write($"{Environment.NewLine}Press Enter to exit..."); +Console.Read(); +// \ No newline at end of file diff --git a/docs/core/tutorials/with-visual-studio-code.md b/docs/core/tutorials/with-visual-studio-code.md index 1aaf7618017d7..45bee81113cf0 100644 --- a/docs/core/tutorials/with-visual-studio-code.md +++ b/docs/core/tutorials/with-visual-studio-code.md @@ -1,73 +1,154 @@ --- title: Create a .NET console application using Visual Studio Code description: Learn how to create a .NET console application using Visual Studio Code. -ms.date: 11/22/2024 +ms.date: 01/26/2026 +zone_pivot_groups: code-editor-set-one --- # Tutorial: Create a .NET console application using Visual Studio Code +::: zone pivot="vscode" + This tutorial shows how to create and run a .NET console application by using Visual Studio Code. +In this tutorial, you: + +> [!div class="checklist"] +> +> * Launch Visual Studio Code with a C# development environment. +> * Create a "HelloWorld" .NET console application. +> * Enhance the app to prompt the user for their name and display it in the console window. + +::: zone-end + +::: zone pivot="codespaces" + +This tutorial shows how to create and run a .NET console application by using GitHub Codespaces. + +In this tutorial, you: + +> [!div class="checklist"] +> +> * Launch a GitHub Codespace with a C# development environment. +> * Create a "HelloWorld" .NET single-file app. +> * Enhance the app to prompt the user for their name and display it in the console window. + +::: zone-end + ## Prerequisites +::: zone pivot="vscode" + [!INCLUDE [Prerequisites](../../../includes/prerequisites-basic-winget.md)] +::: zone-end + +::: zone pivot="codespaces" + +- A GitHub account to use [GitHub Codespaces](https://github.com/codespaces). If you don't already have one, you can create a free account at [GitHub.com](https://github.com). + +::: zone-end + ## Create the app +::: zone pivot="vscode" + Create a .NET console app project named "HelloWorld". 1. Start Visual Studio Code. 1. Go to the Explorer view and select **Create .NET Project**. Alternatively, you can bring up the Command Palette using Ctrl+Shift+P (Command+Shift+P on MacOS) and then type ".NET" and find and select the .NET: New Project command. + :::image type="content" source="media/with-visual-studio-code/create-dotnet-project.png" alt-text="The .NET: New Project command in the Command Palette"::: + 1. After selecting the command, you need to choose the project template. Choose **Console App**. 1. Select the location where you would like the new project to be created. 1. Give your new project a name, "HelloWorld". -1. Select to **Show all template options**. Set **Do not use top-level statements** to **true**. And finally, select **Create Project**. +1. Select **.sln** for the solution file format. -1. In the **Do you trust the authors of the files in this folder?** dialog, select **Yes, I trust the authors**. You can trust the authors because this folder only has files generated by .NET and added or modified by you. +1. Select **Create Project**. -1. Open the *Program.cs* file to see the simple application created by the template: +1. The project is created and the *Program.cs* file opens. You see the simple application created by the template: ```csharp - namespace HelloWorld; - - class Program - { - static void Main(string[] args) - { - Console.WriteLine("Hello, World!"); - } - } + // See https://aka.ms/new-console-template for more information + Console.WriteLine("Hello, World!"); ``` - The code defines a class, `Program`, with a single method, `Main`, that takes a array as an argument. `Main` is the application entry point, the method that's called automatically by the runtime when it launches the application. Any command-line arguments supplied when the application is launched are available in the *args* array. The code in `Main` calls the method to display a message in the console window. + The code defines a class, `Program`, that calls the method to display a message in the console window. - C# has a feature named [top-level statements](../../csharp/fundamentals/program-structure/top-level-statements.md) that lets you omit the `Program` class and the `Main` method. This tutorial doesn't use this feature. Whether you use it in your programs is a matter of style preference. By setting **Do not use top-level statements to true** when you created the project, you prevented top-level statements from being used. +::: zone-end + +::: zone pivot="codespaces" + +### Open Codespaces + +Start a GitHub Codespace with the tutorial environment. + +1. Open a browser window and navigate to the [tutorial codespace](https://github.com/dotnet/tutorial-codespace) repository. + +1. Select the green **Code** button, and then the **Codespaces** tab. + +1. Select the `+` sign or the green **Create codespace on main** button to create a new Codespace using this environment. + + :::image type="content" source="media/with-visual-studio-code/create-codespace-on-main.png" alt-text="Create a new Codespace from the tutorial repository"::: + +### Create a .NET file-based app + +In Codespaces, you'll create a [file-based app](../sdk/file-based-apps.md). File-based apps let you build .NET applications from a single C# file without creating a traditional project file. + +1. When your codespace loads, right-click on the *tutorials* folder and select **New File...**. Enter the name *HelloWorld.cs* and then press Enter. + + :::image type="content" source="media/with-visual-studio-code/codespaces-create-new-file.png" alt-text="Create a new file named HelloWorld.cs in the tutorials folder"::: + +1. *HelloWorld.cs* opens in the editor. Type or copy the following code into the file: + + :::code language="csharp" source="./snippets/with-visual-studio-code/csharp/HelloWorld.cs" id="HelloWorld"::: + +::: zone-end ## Run the app +::: zone pivot="vscode" + To run your app, select **Run** > **Run without Debugging** in the upper menu, or use the keyboard shortcut (Ctrl+F5). -If asked to select a debugger, select **C#**, then select **C#: HelloWorld** +If asked to select a debugger, select **C#** as the debugger, then select **C#: Debug Active File** as the Launch configuration. + +The program displays "Hello, World!" and ends. + +::: zone-end + +::: zone pivot="codespaces" + +In the terminal window, make sure the tutorials folder is the current folder, and run your program: + +```dotnetcli +cd tutorials +dotnet HelloWorld.cs +``` The program displays "Hello, World!" and ends. +::: zone-end + ## Enhance the app Enhance the application to prompt the user for their name and display it along with the date and time. +::: zone pivot="vscode" + 1. Open *Program.cs*. -1. Replace the contents of the `Main` method in *Program.cs*, which is the line that calls `Console.WriteLine`, with the following code: +1. Replace the contents of the class with the following code: :::code language="csharp" source="./snippets/with-visual-studio/csharp/Program-Read.cs" id="MainMethod"::: - This code displays a prompt in the console window and waits until the user enters a string followed by the Enter key. It stores this string in a variable named `name`. It also retrieves the value of the property, which contains the current local time, and assigns it to a variable named `currentDate`. And it displays these values in the console window. Finally, it displays a prompt in the console window and calls the method to wait for user input. + This code displays a prompt in the console window and waits until the user enters a string followed by the Enter key. It stores this string in a variable named `name`. It also retrieves the value of the property, which contains the current local time, and assigns it to a variable named `currentDate`. And it displays these values in the console window. Finally, it displays a prompt in the console window and calls the method to wait for user input. - is a platform-independent and language-independent way to represent a line break. It's the same as `\n` in C#. + is a platform-independent and language-independent way to represent a line break. The dollar sign (`$`) in front of a string lets you put expressions such as variable names in curly braces in the string. The expression value is inserted into the string in place of the expression. This syntax is referred to as [interpolated strings](../../csharp/language-reference/tokens/interpolated.md). @@ -80,14 +161,63 @@ Enhance the application to prompt the user for their name and display it along w 1. Respond to the prompt by entering a name and pressing the Enter key. - :::image type="content" source="media/debugging-with-visual-studio-code/run-modified-program.png" alt-text="Terminal window with modified program output"::: + :::image type="content" source="media/with-visual-studio-code/run-program-class.png" alt-text="Terminal window with modified program output"::: + + Press Enter to exit the program. + +::: zone-end + +::: zone pivot="codespaces" + +1. Update *HelloWorld.cs* with the following code: + + :::code language="csharp" source="./snippets/with-visual-studio-code/csharp/HelloWorld.cs" id="MainMethod"::: + + This code displays a prompt in the console window and waits until the user enters a string followed by the Enter key. It stores this string in a variable named `name`. It also retrieves the value of the property, which contains the current local time, and assigns it to a variable named `currentDate`. And it displays these values in the console window. Finally, it displays a prompt in the console window and calls the method to wait for user input. + + is a platform-independent and language-independent way to represent a line break. + + The dollar sign (`$`) in front of a string lets you put expressions such as variable names in curly braces in the string. The expression value is inserted into the string in place of the expression. This syntax is referred to as [interpolated strings](../../csharp/language-reference/tokens/interpolated.md). + +1. Run the updated app using the following command: + + ```dotnetcli + dotnet HelloWorld.cs + ``` + +1. Respond to the prompt by entering a name and pressing the Enter key. + + You'll see output similar to the following: + + ```output + What is your name? Mark + Hello, Mark, on 1/29/2026 at 4:40 PM! + Press Enter to exit... + ``` + + Press Enter to exit the program. -1. Press Enter to exit the program. +::: zone-end ## Additional resources +::: zone pivot="vscode" + * [Setting up Visual Studio Code](https://code.visualstudio.com/docs/setup/setup-overview) +::: zone-end + +::: zone pivot="codespaces" + +* [GitHub Codespaces documentation](https://docs.github.com/codespaces) +* [Getting started with GitHub Codespaces](https://docs.github.com/codespaces/getting-started) + +## Cleanup resources + +GitHub automatically deletes your Codespace after 30 days of inactivity. If you plan to explore more tutorials in this series, you can leave your Codespace provisioned. If you're ready to visit the [.NET site](https://dotnet.microsoft.com/download/dotnet) to download the .NET SDK, you can delete your Codespace. To delete your Codespace, open a browser window and navigate to [your Codespaces](https://github.com/codespaces). You see a list of your codespaces in the window. Select the three dots (`...`) in the entry for the learn tutorial codespace. Then select "delete". + +::: zone-end + ## Next steps In this tutorial, you created a .NET console application. In the next tutorial, you debug the app. diff --git a/docs/framework/install/dotnet-35-windows-11-faq.yml b/docs/framework/install/dotnet-35-windows-11-faq.yml new file mode 100644 index 0000000000000..25a9e947b61b1 --- /dev/null +++ b/docs/framework/install/dotnet-35-windows-11-faq.yml @@ -0,0 +1,75 @@ +### YamlMime:FAQ +metadata: + title: .NET Framework 3.5 on Windows 11 FAQ + description: "This article answers frequently asked questions about .NET Framework 3.5 on Windows 11." + titleSuffix: "" + ms.topic: faq + ms.date: 02/02/2026 + ai-usage: ai-assisted + +title: .NET Framework 3.5 on Windows 11 FAQ +summary: | + This article answers frequently asked questions about .NET Framework 3.5 on Windows 11. For more information, see [Install .NET Framework 3.5 on Windows 11](dotnet-35-windows-11.md). + + [!INCLUDE [dotnet-35-installer](includes/dotnet-35-installer.md)] + +sections: + - name: Availability and lifecycle + questions: + - question: Is .NET Framework 3.5 included in Windows 11? + answer: | + Your Windows 11 version determines availability: + + - Windows 11 Insider Preview Build 27965 and later versions. + + No. Windows doesn't include .NET Framework 3.5 as a built-in or optional component. + + - Windows 11 25H2 and earlier versions. + + Yes. Windows includes .NET Framework 3.5 as a built-in optional component. Enable it through Windows Features on Demand. + + - question: How long is the .NET Framework 3.5 standalone installer supported? + answer: Support ends January 9, 2029, according to the official [Microsoft .NET Framework lifecycle policy](/lifecycle/products/microsoft-net-framework). + + - question: When I upgrade to a newer version of Windows, is .NET Framework 3.5 included or persisted? + answer: No. When you upgrade Windows to the next release, reinstall .NET Framework 3.5. + + - name: Installation and deployment + questions: + - question: How do I get .NET Framework 3.5 if my application requires it? + answer: Use the standalone installer. For more details, including a link to the installer, see [Announcing Windows 11 Insider Preview Build 27965 (Canary Channel)](https://blogs.windows.com/windows-insider/2025/10/08/announcing-windows-11-insider-preview-build-27965-canary-channel/). + + - question: Are silent installs supported for the new .NET Framework 3.5 standalone installer? + answer: Yes. Use `/q` and `/quiet` command-line options for unattended deployment. + + - question: Can I apply .NET Framework 3.5 to an offline Windows image? + answer: No. Offline installation and servicing isn't supported because .NET Framework 3.5 is no longer an optional Windows Feature on Demand component. DISM and other tools that customize offline Windows deployment images can't manage .NET Framework 3.5. Use **online servicing** to modify a Windows installation. For more information, see [Modify a Windows image](/windows-hardware/manufacture/desktop/modify-an-image?view=windows-11). + + - name: Migration and support + questions: + - question: What is the recommended migration path? + answer: | + Update your application from .NET Framework to .NET. If you can't move to .NET, update your application to .NET Framework 4.8.1. For more information, see [Microsoft .NET Framework lifecycle policy](/lifecycle/products/microsoft-net-framework). + + - question: Where can enterprises and ISVs get additional help with compatibility? + answer: | + Use the [Microsoft FastTrack – App Assure](/microsoft-365/fasttrack/windows-365-and-app-assure#app-assure) program for personalized migration and compatibility assistance. + + - name: Troubleshooting + questions: + - question: | + When I try to run a legacy .NET Framework 3.5 application or its installer, I see a "Program Compatibility Assistant" or a Microsoft .NET Framework runtime message box. Is this expected? + answer: | + Yes. Your application or its installer requires .NET Framework 3.5 to run. The message box links to this document. + + - question: | + My .NET Framework 3.5 application displays an unclear message, like "runtime error" without further guidance when I don't have .NET 3.5 installed. Is this expected? + answer: | + Legacy applications might handle the missing dependency in various ways, including unclear messages. Use the mitigation guidance in this document or contact your software vendor for more information. + +additionalContent: | + ## Related content + + - [Install .NET Framework 3.5 on Windows 11](dotnet-35-windows-11.md) + - [Developers and .NET Framework 3.5](dotnet-35-windows.md#developers-and-net-framework-35) + diff --git a/docs/framework/install/dotnet-35-windows-11.md b/docs/framework/install/dotnet-35-windows-11.md new file mode 100644 index 0000000000000..9e28c5f81d675 --- /dev/null +++ b/docs/framework/install/dotnet-35-windows-11.md @@ -0,0 +1,72 @@ +--- +title: Install .NET Framework 3.5 on Windows 11 +description: Learn how to install .NET Framework 3.5 on Windows 11. .NET Framework 3.5 can run apps that target .NET Framework 1.0 through 3.5. +ms.date: 02/02/2026 +ai-usage: ai-assisted +--- +# Install .NET Framework 3.5 on Windows 11 + +.NET Framework 3.5 is supported on Windows 11. How you obtain .NET Framework 3.5 depends on which version of Windows 11 you're using. Use the following list to identify the installation method that's applicable to you: + +- [Windows 11 25H2 and earlier versions.](dotnet-35-windows.md#install-net-framework-35-on-demand) +- [Windows 11 Insider Preview Build 27965 and later versions.](#windows-11-insider-preview-build-27965-and-later) + +## Windows 11 Insider Preview Build 27965 and later + +[!INCLUDE [dotnet-35-installer](includes/dotnet-35-installer.md)] + +For more information about this change to .NET Framework 3.5, see [.NET Framework 3.5 on Windows 11 FAQ](dotnet-35-windows-11-faq.yml). + +## .NET Framework 3.5 optional components + +_Applies to **Windows 11 Insider Preview Build 27965 and later**_ + +The following optional .NET Framework 3.5 components were previously available as Windows Features on Demand. Windows 11 Insider Preview Build 27965 removes these components: + +- ASP.NET 3.5 +- .NET Extensibility 3.5 +- WCF HTTP Activation +- WCF non-HTTP Activation + +## How to enable ASP.NET 3.5 and WCF in IIS + +Starting with Windows 11 Insider Preview Build 27965, ASP.NET 3.5 and WCF require additional registration to run in IIS. + +Enable ASP.NET 3.5 on your device using the [`Enable-ASPNet35.ps1`](https://go.microsoft.com/fwlink/?linkid=2348600&clcid=0x409) PowerShell script. The script enables the functionality of the following optional components that have been removed from Windows: + +- ASP.NET 3.5 +- .NET Extensibility 3.5 + +> [!NOTE] +> The script only restores the functionality of these optional components so that applications that depend on them can continue working. The optional components are still missing from Windows 11 and tools like DISM won't detect these optional components as present after running the script. + +### Prerequisites + +- Windows Insider Preview Build 27965 or later +- Windows PowerShell 5.1 +- .NET Framework 3.5 +- The Web Server (IIS) feature or role enabled, along with the **ISAPI Filters** and **ISAPI Extensions** optional components +- An administrative PowerShell command window + +### Run the script + +1. Download the [`Enable-ASPNet35.ps1`](https://go.microsoft.com/fwlink/?linkid=2348600&clcid=0x409) script to a local directory. +1. Open a Windows PowerShell command window **as Administrator**. +1. Change the execution policy to allow scripts downloaded from the Internet and signed by trusted publishers: + + ```powershell + Set-ExecutionPolicy RemoteSigned + ``` + + For more information about execution policy settings, see [Set-ExecutionPolicy](/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-5.1&preserve-view=true). + +1. Go to the directory where you downloaded the script. +1. Run the script: + + ```powershell + .\Enable-ASPNet35.ps1 + ``` + +## How to determine which version of Windows you're using + +[!INCLUDE [dotnet-determine-windows-version](includes/dotnet-determine-windows-version.md)] diff --git a/docs/framework/install/dotnet-35-windows.md b/docs/framework/install/dotnet-35-windows.md index affb0d3078c6a..a49a89ebe04cb 100644 --- a/docs/framework/install/dotnet-35-windows.md +++ b/docs/framework/install/dotnet-35-windows.md @@ -1,11 +1,13 @@ --- title: Install .NET Framework 3.5 on Windows description: Learn how to install .NET Framework 3.5 on Windows and Windows Server. .NET Framework 3.5 can run apps that target .NET Framework 1.0 through 3.5. -ms.date: 07/10/2025 +ms.date: 02/02/2026 ai-usage: ai-assisted --- # Install .NET Framework 3.5 on Windows and Windows Server +[!INCLUDE [dotnet-35-find-update](includes/dotnet-35-find-update.md)] + .NET Framework is software that allows programs to run on your computer. Think of it as an engine that apps need to function—just like a car needs an engine to run, some apps need .NET Framework to work. This article helps you install version 3.5, which is an older version that some apps still require. You might need .NET Framework 3.5 to run an app on Windows or Windows Server. Windows and Windows Server come with .NET Framework 4, which doesn't support apps built with .NET Framework 1.1 through 3.5. To run these apps, install .NET Framework 3.5. If you're a developer that requires .NET Framework 3.5, see the section [Developers and .NET Framework 3.5](#developers-and-net-framework-35). @@ -17,6 +19,8 @@ If you're a developer that requires .NET Framework 3.5, see the section [Develop You might see the following configuration dialog if you try to run an app that requires an older version of .NET Framework. Depending on your version of Windows, the dialog might be slightly different. Choose **Download and install this feature** to enable .NET Framework 3.5. This option requires an internet connection. +[!INCLUDE [dotnet-35-find-update](includes/dotnet-35-find-update.md)] + :::image type="content" source="./media/dotnet-35-windows/dotnet-framework-installation-dialog.png" alt-text="Screenshot of the .NET Framework installation dialog."::: ### Why am I getting this pop-up? @@ -27,6 +31,8 @@ You might see the following configuration dialog if you try to run an app that r Enable .NET Framework 3.5 through the **Add Roles and Features Wizard**. +[!INCLUDE [dotnet-35-find-update](includes/dotnet-35-find-update.md)] + 1. Press the Start :::image type="icon" source="media/dotnet-35-windows/windows-keyboard-logo.png" border="false"::: button on the taskbar. 1. Search for **Add Roles and Features Wizard** and open it. 1. Search for **Windows Features** and open it. The **Turn Windows features on or off** dialog box appears. @@ -38,7 +44,7 @@ Enable .NET Framework 3.5 through the **Add Roles and Features Wizard**. ## Enable .NET Framework 3.5 on Windows -You can enable the .NET Framework 3.5 through the Windows Control Panel. This option requires an internet connection. +[!INCLUDE [dotnet-35-windows-11-caution-version](includes/dotnet-35-windows-11-caution-version.md)] 1. Press the Start :::image type="icon" source="media/dotnet-35-windows/windows-keyboard-logo.png" border="false"::: button on the taskbar. 1. Search for **Windows Features** and open it. The **Turn Windows features on or off** dialog box appears. @@ -50,7 +56,13 @@ You don't need to select the child items for **Windows Communication Foundation ## Download the offline installer -The .NET Framework 3.5 SP1 offline installer is available for Windows versions **prior to Windows 10 and Windows Server 2016**. For more information, see [.NET Framework 3.5 SP1 download page](https://dotnet.microsoft.com/download/dotnet-framework/net35-sp1?wt.mc_id=install-docs). +[!INCLUDE [dotnet-35-windows-11-caution-version](includes/dotnet-35-windows-11-caution-version.md)] + +The .NET Framework 3.5 SP1 offline installer is available for Windows versions **prior to Windows 10 and Windows Server 2016**, such as **Windows 8**. For more information, see [.NET Framework 3.5 SP1 download page](https://dotnet.microsoft.com/download/dotnet-framework/net35-sp1?wt.mc_id=install-docs). + +[!INCLUDE [dotnet-35-find-update](includes/dotnet-35-find-update.md)] + +### Windows 10 Starting with Windows 10 and Windows Server 2016 operating systems, the only supported way of installing .NET Framework 3.5 in an offline mode is by using the original installation media's _:::no-loc text="cab":::_ files. For more information, see [Microsoft .NET Framework 3.5 deployment considerations](/windows-hardware/manufacture/desktop/microsoft-net-framework-35-deployment-considerations). @@ -65,6 +77,20 @@ If you still can't resolve your installation issue or you don't have an internet ## Developers and .NET Framework 3.5 +[!INCLUDE [dotnet-35-installer](includes/dotnet-35-installer.md)] + +For more information about this change to .NET Framework 3.5, see [.NET Framework 3.5 on Windows 11 FAQ](dotnet-35-windows-11-faq.yml). + +Additionally, the optional components that rely on .NET Framework 3.5 have also been removed: + +- ASP.NET 3.5 +- .NET Extensibility 3.5 +- WCF HTTP Activation +- WCF non-HTTP Activation + +> [!IMPORTANT] +> Microsoft strongly recommends you upgrade your application from .NET Framework to modern .NET, such as .NET 10. If you can't move to .NET, upgrade your application to .NET Framework 4.8 or 4.8.1. For more information about upgrading from .NET Framework 3.5, see [.NET Framework 4 migration issues](../migration-guide/net-framework-4-migration-issues.md) and [Overview of porting from .NET Framework to .NET](../../core/porting/framework-overview.md). + If you're a developer that maintains existing software and you need to use .NET Framework 3.5, enable it with the following steps: 1. Install .NET Framework 3.5 on your system using the instructions in this article. diff --git a/docs/framework/install/guide-for-developers.md b/docs/framework/install/guide-for-developers.md index 5c654f5b2754d..96771cae6eb21 100644 --- a/docs/framework/install/guide-for-developers.md +++ b/docs/framework/install/guide-for-developers.md @@ -1,7 +1,7 @@ --- title: "Install the .NET Framework developer pack or redistributable" description: "Developers can download and install the .NET Framework developer pack and targeting pack. You can include the .NET Framework redistributable with your apps." -ms.date: 07/10/2025 +ms.date: 02/02/2026 helpviewer_keywords: - ".NET Framework redistributable package, downloading" - ".NET Framework, installing" diff --git a/docs/framework/install/includes/dotnet-35-find-update.md b/docs/framework/install/includes/dotnet-35-find-update.md new file mode 100644 index 0000000000000..5aedd080fe807 --- /dev/null +++ b/docs/framework/install/includes/dotnet-35-find-update.md @@ -0,0 +1,8 @@ +--- +ms.author: adegeo +ms.date: 02/02/2026 +ms.topic: include +--- + +> [!IMPORTANT] +> .NET Framework 3.5 was released in 2008. Before installing .NET Framework 3.5, try to find an updated version of your software that uses a new version of .NET Framework or .NET. diff --git a/docs/framework/install/includes/dotnet-35-installer.md b/docs/framework/install/includes/dotnet-35-installer.md new file mode 100644 index 0000000000000..8208aa0f83848 --- /dev/null +++ b/docs/framework/install/includes/dotnet-35-installer.md @@ -0,0 +1,8 @@ +--- +ms.author: adegeo +ms.date: 02/02/2026 +ms.topic: include +ai-usage: ai-assisted +--- + +Starting with Windows 11 Insider Preview Build 27965, .NET Framework 3.5 is no longer available as a Windows Features on Demand optional component. Install it using a standalone installer (also known as an offline installer). For more information, see [Announcing Windows 11 Insider Preview Build 27965 (Canary Channel)](https://blogs.windows.com/windows-insider/2025/10/08/announcing-windows-11-insider-preview-build-27965-canary-channel/). diff --git a/docs/framework/install/includes/dotnet-35-windows-11-caution-version.md b/docs/framework/install/includes/dotnet-35-windows-11-caution-version.md new file mode 100644 index 0000000000000..3e6b2e0821bf2 --- /dev/null +++ b/docs/framework/install/includes/dotnet-35-windows-11-caution-version.md @@ -0,0 +1,8 @@ +--- +ms.author: adegeo +ms.date: 02/02/2026 +ms.topic: include +--- + +> [!CAUTION] +> If you're using Windows 11 Insider Preview Build 27965 or later, see [Install .NET Framework 3.5 on Windows 11](../dotnet-35-windows-11.md). diff --git a/docs/framework/install/includes/dotnet-determine-windows-version.md b/docs/framework/install/includes/dotnet-determine-windows-version.md new file mode 100644 index 0000000000000..9accae4d25b34 --- /dev/null +++ b/docs/framework/install/includes/dotnet-determine-windows-version.md @@ -0,0 +1,22 @@ +--- +ms.author: adegeo +ms.date: 02/02/2026 +ms.topic: include +--- + +There are a few different ways you can find the version of Windows you're using: + +- Select [this (ms-settings:about) link](ms-settings:about) which might open the Settings app. + + 1. Scroll down to the **Windows specifications** section and find the **Version** field. + +- Use the start menu: + + 1. Press the Windows key to open the **Start** menu. + 1. Type `Settings` to find the **Settings** app and open it. + 1. Scroll down to the **Windows specifications** section and find the **Version** field. + +- Run the `winver.exe` app: + + 1. Press the Windows+R keyboard shortcut to open the **Run** dialog. + 1. Type `winver.exe` and press Enter. diff --git a/docs/framework/install/on-windows-and-server.md b/docs/framework/install/on-windows-and-server.md index 2b544b59a892c..04731d7eb9b4f 100644 --- a/docs/framework/install/on-windows-and-server.md +++ b/docs/framework/install/on-windows-and-server.md @@ -26,12 +26,6 @@ The following versions of .NET Framework are still supported: - [.NET Framework 4.6.2](https://dotnet.microsoft.com/download/dotnet-framework/net462) (support ends January 12, 2027) - [.NET Framework 3.5 Service Pack 1](https://dotnet.microsoft.com/download/dotnet-framework/net35-sp1) (support ends January 9, 2029) -### .NET Framework 3.5 - -.NET Framework 3.5 is still supported by Microsoft, even though it's an older version of .NET Framework. However, only the .NET Framework 3.5 runtime is supported, which runs apps. Developing new apps that target .NET Framework 3.5 isn't supported. This version of .NET Framework supports running apps that target versions 1.0 through 3.5, and can be installed alongside .NET Framework 4. - -If you try to run an app that targets .NET Framework 1.0 through 3.5, and .NET Framework 3.5 is missing, you're prompted to install it. For more information, see [Install .NET Framework 3.5 on Windows](dotnet-35-windows.md). - ### .NET Framework 4.x All .NET Framework 4.x versions are in-place updates. Only a single 4.x version can be present on Windows. Because .NET Framework is installed as part of Windows, consider that: @@ -40,6 +34,14 @@ All .NET Framework 4.x versions are in-place updates. Only a single 4.x version - If the OS comes preinstalled with a particular .NET Framework version, you can't install a previous 4.x version on the same machine. - If you install a later version, you don't have to first uninstall the previous version. +### .NET Framework 3.5 + +.NET Framework 3.5 is supported by Microsoft, even though it's an older version of .NET Framework. However, only the .NET Framework 3.5 runtime is supported, which runs apps. Developing new apps that target .NET Framework 3.5 isn't supported. This version of .NET Framework supports running apps that target versions 1.0 through 3.5, and can be installed alongside .NET Framework 4. + +[!INCLUDE [dotnet-35-installer](includes/dotnet-35-installer.md)] + +If you try to run an app that targets .NET Framework 1.0 through 3.5, and .NET Framework 3.5 is missing, you're prompted to install it. For more information, see [Install .NET Framework 3.5 on Windows](dotnet-35-windows.md). + ## Developers and Visual Studio Visual Studio uses .NET Framework Developer Packs to support targeting specific versions of .NET Framework 4. If you're a developer who must work on a project targeting an old version of .NET Framework 4, install the corresponding developer pack. For more information, see [Install .NET Framework for developers](guide-for-developers.md). diff --git a/docs/framework/toc.yml b/docs/framework/toc.yml index 9caa626263c34..ba053f8c1f783 100644 --- a/docs/framework/toc.yml +++ b/docs/framework/toc.yml @@ -34,7 +34,13 @@ items: - name: Troubleshoot 'This application could not be started' href: install/application-not-started.md - name: .NET Framework 3.5 - href: install/dotnet-35-windows.md + items: + - name: Windows 11 + href: install/dotnet-35-windows-11.md + - name: Windows 11 and .NET Framework 3.5 FAQ + href: install/dotnet-35-windows-11-faq.yml + - name: Windows 10, Windows Server, and other Windows + href: install/dotnet-35-windows.md - name: Migration guide items: - name: Overview @@ -108,7 +114,7 @@ items: href: migration-guide/version-compatibility.md - name: Configure an app to support .NET Framework 4 or later href: migration-guide/how-to-configure-an-app-to-support-net-framework-4-or-4-5.md - - name: Migrate from .NET Framework 1.1 + - name: Migrate from .NET Framework 1.1 - 3.5 href: migration-guide/migrating-from-the-net-framework-1-1.md - name: .NET Framework 4 migration issues href: migration-guide/net-framework-4-migration-issues.md diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml index f558c9f7cc20b..076471bc5b99d 100644 --- a/docs/navigate/devops-testing/toc.yml +++ b/docs/navigate/devops-testing/toc.yml @@ -243,6 +243,8 @@ items: href: ../../core/testing/mstest-analyzers/mstest0061.md - name: MSTEST0062 href: ../../core/testing/mstest-analyzers/mstest0062.md + - name: MSTEST0063 + href: ../../core/testing/mstest-analyzers/mstest0063.md - name: Migration items: - name: Migrate from MSTest v1 to v3 diff --git a/docs/zone-pivot-groups.yml b/docs/zone-pivot-groups.yml index 4cb474bfa2ac2..41cf8432c85d1 100644 --- a/docs/zone-pivot-groups.yml +++ b/docs/zone-pivot-groups.yml @@ -160,3 +160,11 @@ groups: title: OpenAI - id: ollama title: Ollama +- id: code-editor-set-one + title: Code editor + prompt: Choose a code editor + pivots: + - id: vscode + title: Visual Studio Code + - id: codespaces + title: GitHub Codespaces