Porting Existing ASP.NET Apps to .NET 7

cover image


Microsoft Developer Division, .NET, and Visual Studio product teams

A division of Microsoft Corporation

One Microsoft Way

Redmond, Washington 98052-6399

Copyright © 2023 by Microsoft Corporation

All rights reserved. No part of this book's contents may be reproduced or transmitted in any form or by any means without the written permission of the publisher.

This book is provided "as-is" and expresses the author's views and opinions. The views, opinions, and information expressed in this book, including URL and other Internet website references, may change without notice.

Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

Microsoft and the trademarks listed at https://www.microsoft.com on the "Trademarks" webpage are trademarks of the Microsoft group of companies.

Mac and macOS are trademarks of Apple Inc.

The Docker whale logo is a registered trademark of Docker, Inc. Used by permission.

All other marks and logos are property of their respective owners.


Steve "ardalis" Smith, Software Architect and Trainer - Ardalis.com

Participants and Reviewers:

Nish Anil, Senior Program Manager, .NET team, Microsoft

Mike Rousos, Principal Software Engineer, .NET team, Microsoft

Scott Addie, Senior Content Developer, .NET team, Microsoft

David Pine, Senior Content Developer, .NET team, Microsoft


This guide covers .NET 7 and updates related to the same technology "wave" (that is, Azure and other third-party technologies) coinciding in time with the .NET 7 release. This book covers migration of apps that are currently running on .NET Framework 4.x.

Who should use this guide

This guide's audience is developers, development leads, and architects who are interested in migrating their existing apps written for ASP.NET MVC and Web API (.NET Framework 4.x) to the latest .NET version. ASP.NET Web Forms developers will benefit from this guide but should also read the Blazor for ASP.NET Web Forms Developers e-book.

A secondary audience is technical decision-makers planning when to move their apps to .NET 7.

The target audience for this book is .NET developers with large, existing apps that run on ASP.NET MVC and Web API. Apps built on ASP.NET Web Forms are outside of the focus of this book, though much of the information comparing .NET Framework and .NET Core/latest may still be relevant.

How you can use this guide

You can read this book straight through, as we expect many readers to do. This book will provide you first with considerations for whether you should port your app at all. That content is followed by architectural differences between .NET Framework and .NET Core. From there, you'll learn strategies for migrating a large solution over time and how to port a real app. Next, the book includes deployment scenarios that address the need to run different apps while appearing as a single app to users. The book concludes with two case studies describing real apps that have migrated from ASP.NET MVC to ASP.NET Core.

Whether or not you choose to start from the first chapter, you can reference any of these chapters to learn about specific concepts:

This guide is available both in PDF form and online. Feel free to forward this document or links to its online version to your team to ensure a common understanding of these concepts.

Send your feedback

This book and related samples are constantly evolving, so your feedback is welcomed. If you have comments about how this book can be improved and you're reading this book on <learn.microsoft.com>, use the Feedback section at the bottom of the page:

Feedback section of all .NET docs article footers.

As highlighted in the preceding screen capture, the feedback section allows you to submit feedback for:

  • This product: using the .NET product feedback form.
  • This page: using a GitHub issue template with the page details.

If you're reading this book as a PDF, you can submit feedback by creating a new .NET Docs: GitHub issue or by using the .NET Architecture eBooks: GitHub issue template.