Proposed .NET 7 Breaking Changes

[richlander]

The following list defines breaking changes that are proposed for .NET 7.

Implemented:

• Disable multi-level lookup by default runtime#67022
• Do not add x86 host to PATH on 64-bit machines runtime#69902
• Add implicit RIDs when not specified on self contained option sdk#22314

Planned for .NET 7:

• Enable publishing as Release with PublishRelease sdk#23551

Unclear plan:

• Proposal for vector instruction default designs#173

Moved to .NET 8:

• .NET 8: [breaking] dotnet build/publish produces RID-specific apps by default sdk#23540
• .NET 8: [breaking] dotnet build/publish does not produce an exe/apphost for portable apps by default sdk#23545

No longer honor multi-level-lookup (MLL) for .NET 7+ apps, runtimes and SDKs

Proposal: https://github.com/dotnet/designs/blob/main/accepted/2022/disable-multi-level-lookup-by-default.md
Change: dotnet/runtime#67022
Notice: dotnet/docs#28836

Multi-level-lookup (MLL) -- specified with DOTNET_MULTILEVEL_LOOKUP -- is relevant when an alternate location is specified to look for SDKs and/or runtimes, via DOTNET_ROOT. When enabled, MLL expands the search space for runtimes and SDKs to include the global .NET installation location in addition to the DOTNET_ROOT location. This can result in a runtime or SDK being selected from the global installation location rather than the intended private DOTNET_ROOT location, whether that is desired or not.

Motivation for break:

• MLL results in lots of confusion, both for .NET developers and even for folks working on the .NET platform.
• MLL behavior differs by OS: enabled by default on Windows, not available on any other OS.
• No known scenario where this feature is required.

Stop adding 32-bit .NET to the PATH for .NET 7+ runtimes and SDKs (on x64 machine)

Proposal: dotnet/sdk#22030
Change: dotnet/runtime#69902
Notice: dotnet/runtime#70039

Note: This change was made to .NET Core 3.1, .NET 6, and .NET 7.

When you install .NET, the installer adds the install location to the PATH environment variable. This behavior is sound and enables the OS to find dotnet when you use it. We build multiple .NET for multiple architectures (x86, x64, ...). In some cases, an OS supports multiple architectures and then we need a plan for how multiple .NET locations in the PATH works. In short, it doesn't work well. Going forward, we should only ever add the OS native-architecture .NET install location to the PATH. We already started doing that on Apple M1 (Arm64) machines (we only add the Arm64 .NET to the PATH, not the x64 version). We need to repeat this pattern with Windows now, with the 32-bit .NET build.

Motivation for break:

• Adding multiple builds of .NET to the PATH is incoherent, results in bad UX, and is difficult to explain.
• We have already started down this direction with x64 on Arm64. It makes sense to make the product consistent, by repeating the pattern with x86 on x64 and x86 on Arm64.

dotnet build/publish uses the implicit SDK RID for RID-specific apps by default

Proposal: dotnet/sdk#23539
Change: dotnet/sdk#22314
Notice: not actually breaking

Today, you must specify a RID when you specify "--self-contained". That's not a useful requirement, particularly if you want to app to be able to run in a given environment (like CI) and don't know what that is ahead of time. Instead, the implicit SDK RID should be used in any scenario where a RID is needed but one isn't provided. The most obvious example of that is to produce a self-contained app.

FYI: This is arguably not a breaking change.

Motivation for break:

• The CLI should have good defaults where correct behavior can be provided in absence of the user provided a specific value.
• RID targeting is confusing. We should make it simpler.

dotnet publish/pack produce release assets by default

Proposal: dotnet/sdk#23551

Our basic guidance to developers since .NET Core 1.0 has been "use build for development and publish for prod". Given that, it would make a lot more sense if publish defaulted to a release build. Debug builds run observably slow (sometimes you can see this with just your eyes; no stopwatch required). It is near certain that plenty of .NET apps are deployed as debug due to the current defaults. The CLI would be much better if it offered more differentiated options. There should probably be a more broad re-assessment of build and publish but I'm not digging into that here. I'm proposing a much more simpler change (that doesn't preclude broader changes later; in fact, this change would encourage them).

Motivation for break:

• release assets have better performance (sometimes by a large margin).
• Some CLI commands bias strongly to prod, which provides us with a good opportunity to provide a differentiated prod experience. We don't want developers deploying debug assets into prod unwittingly. Differentiated experiences can help that.

dotnet build/publish produces RID-specific apps by default

Proposal: dotnet/sdk#23540

The .NET SDK has produced portable apps since .NET Core 1.0. That may or may not have made sense, but it no longer does now. Portable apps are bigger, slower to startup, and less reliable in some scenarios. In addition, portable apps are not fully coherent since they have a RID-specific executable but portable assets. That means that you can use the executable for one RID environment and cannot for any other. It's an odd design choice. A perfect example is containers. RID-specific apps are always better for containers. Another example is client apps. Client apps require an executable, such that they should always be RID-specific.

Motivation for break:

• Portable apps are good for a small subset of scenarios.
• RID-specific apps are the only good option for a variety of popular scenarios.

dotnet build/publish does not produce an exe/apphost for portable apps by default

Proposal: dotnet/sdk#23545

Portable apps are intended to run in multiple environments. By definition, an executable is RID-specific and therefore only compatible with one of the environments in which a portable app can run. It's possible that developers are happy with this asymmetry, but should opt into that experience.

Motivation for break:

• The apphost makes portable apps incoherent.
• It is easier to explain how to use portable apps in absence of an executable apphost.

Precompile with AVX2 (x64) or NEON (Arm64) instructions for better startup performance

Proposal: dotnet/designs#173

Vector (SIMD) instructions are now one of the key performance pillars of the .NET platform. Today, pre-compiled Ready-to-Run (R2R) code targets the SSE2 instruction set on x64. We require the JIT to tier the platform to tier 1 in order to take advantage of larger/newer vector instructions (like AVX2). That model penalizes startup on modern hardware and also places a hard dependency on tiered compilation for good performance. Ideally, R2R code was already very good, and tiered compilation was reserved for only the highest value methods. We can achieve that by compiling R2R code with AVX2 (x64) and NEON (Arm64) by default. We would not change the Windows 32-bit or Arm 32-bit builds.

Note: After this change, machines with AVX2 will have better performance, while machines w/o it will end up with worse performance since some R2R methods will be rejected and require jitting where they previously did not.

Motivation for break:

• Highest performance, including at startup.
• Align product to modern hardware.

For additional context, SSE2-compatible hardware was first released in 2000, and the same for AVX2 in 2013.

[richlander]

/cc @vitek-karas, @jkotas, @marcpopMSFT, @baronfel, @tannergooding, @ericstj, @joeloff, @dleeapho, @mangod9

[tannergooding]

Overall LGTM.

One nit is that "Require AVX2 (x64) or NEON (Arm64) hardware for best performance" is a confusing statement. We aren't requiring AVX2 and we will continue working on hardware without. Instead we are assuming that the hardware will have AVX2 support by default and will prep our assemblies using crossgen that assumes AVX2 is available. This will provide faster startup and steady state throughput on modern hardware but will force older hardware to reject the impacted R2R method entries and fallback to jitting them instead.

For ARM64, Neon (otherwise known as AdvSimd) is already considered baseline and there should be no "break" here.

Also worth noting that the below is inaccurate:

For additional context, SSE2-compatible hardware was first released in 2004, and the same for AVX2 in 2013.

For reference, SSE2 was introduced in 2000 alongside the Pentium 4. It's been required on all x64 CPUs which were first introduced in 2003. AVX2 was introduced in 2013 and has been available on most CPUs since then. There are some low-end/budget CPUs (like older Intel Atoms) that have shipped since then without AVX2 support, but they are believe to be a minority overall.

[richlander]

I added a note to clarify and updated the dates. Helps?

[tannergooding]

Yes. I think the wording on the title is the most confusing part, however, and the concern is that its going to show up in some "clickbait" blog post somewhere.

I think changing:

Require AVX2 (x64) or NEON (Arm64) hardware for best performance

to

Precompile with AVX2 (x64) or NEON (Arm64) support for better startup performance

might be better. Thoughts?

[richlander]

Done.

[marcpopMSFT]

Thanks for putting this together. I'm aware of and supportive of most of these. For the SDK implicit RID, I assume that the proposal once written will include the locations we want to enable the default?

I'd need to see the proposal for portable to weigh in on that one as I don't know enough about what our customer expectations are and whether this would cause more confusion than it would save.

[richlander]

Yup. Will do what you've asked.

[joeloff]

Thank you for the PATH writeup @richlander

[samsp-msft]

Another wording one:

dotnet build/publish does not produce an exe/apphost for portable apps by default

how about:

dotnet build/publish for portable apps, by default no longer produces an exe/apphost

[richlander]

Seems like passive construction, right?

[richlander]

@marcpopMSFT -- all of the proposals now have lengthy write-ups. Tell me if that works.

I just added another one on release mode.

[DamianEdwards]

Some of these changes will potentially impact ASP.NET Core scenarios more than console/client scenarios. Indeed some of the existing default behaviors are there because the first version of .NET Core only had ASP.NET Core as a primary workload. Can we please ensure we explicitly loop in folks from the ASP.NET Core & VS web tooling sides to weigh in on all these proposals.

@Tratcher @vijayrkn @sayedihashimi @davidfowl

[richlander]

Yes. publish is the one that was mostly there for ASP.NET Core.

I'm not a fan of the current build/publish dichotomy. Ideally, we'd make this proposed change (release for publish by default), and use that as a way to (re-)start the bigger conversation while not blocking on delivering value (even if the final changes makes this change moot).

[davidfowl]

@richlander The problem is that the proposal doesn't say much about how ASP.NET Core uses publish and what the alternative is. The details are a bit anemic on those scenarios at the moment...