Special thanks to Matthew Wilkin for kindly helping to peer review this article.

特别感谢Matthew Wilkin慷慨地帮助同行审阅本文。

Over recent years, Microsoft has touted the ASP.NET Core framework as the future of ASP.NET. ASP.NET Core is of interest to web professionals on the Microsoft stack. If you’re running web applications on Windows and want to make the upgrade, what are the gotchas? Is the transition to the latest and greatest paved and smooth?

近年来，Microsoft吹捧ASP.NET Core框架作为ASP.NET的未来。 Microsoft堆栈上的Web专业人士对ASP.NET Core感兴趣。 如果您要在Windows上运行Web应用程序并想要进行升级，则有什么陷阱？ 过渡到最新，最出色的铺面且顺利吗？

In this take, I’d like to delve into common pitfalls you may run into when you upgrade to ASP.NET Core — assuming you’re eager to make the switch. As developers, it’s always exciting to get your hands on shiny new tools that make your life easier.

在这种情况下，我想研究一下升级到ASP.NET Core时可能遇到的常见陷阱—假设您急于进行切换。 作为开发人员，动手使用能让您的生活更轻松的闪亮新工具总是令人兴奋的。

For this article, I’ll use “ASP.NET classic” to refer to the legacy ASP.NET framework. I’ll use “ASP.NET Core” to refer to the standard framework Microsoft makes available to ASP.NET developers.

对于本文，我将使用“ ASP.NET classic”来指代旧式ASP.NET框架。 我将使用“ ASP.NET Core”来指代Microsoft提供给ASP.NET开发人员的标准框架。

Microsoft had made positive strides towards making ASP.NET Core cross-platform. The new tooling runs on Linux, macOS, and Windows. It may be comforting to know your back-end code now runs anywhere. This frees you, the developer, from having to code on a Windows box. The new tooling available caters to your personal preferences.

微软在使ASP.NET Core跨平台方面取得了积极进展。 新工具可在Linux，macOS和Windows上运行。 知道您的后端代码现在可以在任何地方运行可能会让您感到欣慰。 这使您(开发人员)无需在Windows框上进行编码。 可用的新工具可满足您的个人喜好。

Coming from ASP.NET classic, a valid assumption is that you’re on the Windows platform. To you, going cross-platform may not be relevant right at this moment. Up until now, ASP.NET classic has been a first-class citizen and exclusive to Windows. This tight integration with Windows and IIS, of course, is both a blessing and a curse.

来自ASP.NET classic，一个有效的假设是您位于Windows平台上。 对您来说，跨平台目前可能并不重要。 到目前为止，ASP.NET classic一直是一流的公民，是Windows专有的。 与Windows和IIS的这种紧密集成当然既是福也是祸。

So, what does ASP.NET Core mean for developers on Windows Server and IIS? Now that ASP.NET Core is cross-platform, what are the implications?

那么，ASP.NET Core对Windows Server和IIS上的开发人员意味着什么？ 现在，ASP.NET Core是跨平台的，这意味着什么？

依赖地狱 (Dependency Hell)

One natural consequence from decoupling from IIS is an explosion of dependencies. ASP.NET Core runs on Kestrel, a separate process that responds to HTTP requests. This means the framework leans on a bunch of dependencies where IIS once stood. These dependencies are basic NuGet packages you can download from the internet.

与IIS分离的自然结果是依赖性的激增。 ASP.NET Core在Kestrel上运行，Kestrel是响应HTTP请求的独立进程。 这意味着该框架依赖于IIS曾经存在的一堆依赖项。 这些依赖项是可以从Internet下载的基本NuGet软件包。

With ASP.NET Core, NuGet is the canonical way to get dependencies. In fact, most of the tooling is now a decoupled NuGet package you can add as a dependency. The tooling you install on your local dev box is only a shim. The intent is to get your app to be self-contained with all its dependencies. The majority of ASP.NET Core comes in modular NuGet packages you plug and play.

使用ASP.NET Core，NuGet是获取依赖关系的规范方法。 实际上，现在大多数工具都是可以将脱机的NuGet包添加为依赖项。 您在本地开发工具箱上安装的工具只是一个垫片。 目的是使您的应用程序具有所有依赖关系。 大多数ASP.NET Core都带有您可以即插即用的模块化NuGet软件包。

This is a fresh take on the old monolithic framework tight-coupled to IIS. ASP.NET Core is cross-platform and means it. What was once leaning on colossal IIS and Windows installs is now reduced to a NuGet package. This makes the framework nimble and more flexible. It’s easier to change a small NuGet dependency than installing modules on your web server.

这是紧密结合到IIS的旧式整体框架的全新尝试。 ASP.NET Core是跨平台的，意味着它。 曾经依靠庞大的IIS和Windows安装的东西现在变成了NuGet软件包。 这使框架变得灵活灵活。 更改小的NuGet依赖关系比在Web服务器上安装模块要容易得多。

But, as often is the case, there are a few gotchas:

但是，通常情况下，有一些陷阱：

• On the local dev machine, the team saw a NuGet packages folder with 1GB worth of dependencies.在本地开发人员计算机上，团队看到了一个N​​uGet软件包文件夹，其中包含1GB的依赖项。
• If your build server is behind a firewall, you upload each tiny dependency — a tedious process.如果您的构建服务器位于防火墙之后，则您将上传每个微小的依赖关系-一个繁琐的过程。
• By default, the tooling brings in meta-packages, which may have extraneous dependencies.默认情况下，该工具会引入元包，这些元包可能具有无关的依赖关系。

One downside with meta-packages is that, if you’re on Windows, you’ll see bizarre dependencies like:

元软件包的一个缺点是，如果您使用Windows，则会看到奇怪的依赖项，例如：

It’s not common to include a Linux and macOS runtime as a dependency, given that you only expect to run this on Windows. Yet, if you want to pass the build, it is necessary. There is a way to reduce your dependency footprint, but not very practical in an enterprise setting. Few professionals have the time to tweak a gig worth of tiny little dependencies. The hope is the tooling will do better and normalize dependencies for you in the future.

考虑到只希望在Windows上运行，将Linux和macOS运行时作为依赖项并不常见。 但是，如果要通过构建，则有必要。 有一种方法可以减少您的依赖范围，但是在企业环境中不是很实用 。 很少有专业人士有时间调整一些微小的依赖关系。 希望该工具将来能为您做得更好，并使您的依赖关系正常化。

There are certain challenges to get a successful build on your build server. My team and I felt like this was going down a roller coaster ride we hadn’t prepared for. An endearing codename within the team for ASP.NET Core was “Fat Lady”, because of all the dependencies.

在构建服务器上成功构建存在某些挑战。 我和我的团队感到这就像我们原本没有准备的过山车一样。 由于所有依赖关系，ASP.NET Core团队中一个讨人喜欢的代号为“ Fat Lady”。

This leaves us with a question. How do you get this sizable framework into a web server?

这给我们留下了一个问题。 您如何将这个可观的框架引入Web服务器？

部署自动化 (Deployment Automation)

If your team has working deployments on ASP.NET classic, you’ll see that a lot has changed. ASP.NET Core uses a new set of tools for deployments.

如果您的团队在ASP.NET classic上具有有效的部署，您将看到很多变化。 ASP.NET Core使用一组新的部署工具。

Coming from ASP.NET classic, the hope was that deployments were reusable. In automation, there’s a set of scripts you use to get changes onto a web server. The scripts that run in automation are often called a deployment pipeline. In Windows, this means PowerShell scripts to ensure reliable and predictable deployments. Having reusable pipelines is one way to ensure consistent deployments.

来自ASP.NET classic，希望是可重用的部署。 在自动化中，有一组脚本可用于将更改更改到Web服务器上。 在自动化中运行的脚本通常称为部署管道。 在Windows中，这意味着PowerShell脚本可确保可靠且可预测的部署。 拥有可重复使用的管道是确保一致部署的一种方法。

The ASP.NET Core tooling uses a separate set of command line tools to create a deployment package. There are nuances with this that will force you to create a new deployment pipeline. For example, MS Build was the CLI tool of choice for ASP.NET classic deployments. With ASP.NET Core, there’s a dotnet publish command to create a package. The subtle differences between the two cast the team into a new pipeline. Unfortunately, much of the existing automation was not reusable.

ASP.NET Core工具使用一组单独的命令行工具来创建部署包。 有一些细微差别，这将迫使您创建新的部署管道。 例如，MS Build是ASP.NET经典部署的首选CLI工具。 使用ASP.NET Core，可以使用dotnet publish命令创建程序包。 两者之间的细微差异使团队进入了新的渠道。 不幸的是，许多现有的自动化措施是不可重用的。

The automation for ASP.NET classic made assumptions that were no longer valid. For us, the goal was to gather together the bare necessities for a good deployment. This took an all-hands-on-deck approach to flesh out all the necessary details.

ASP.NET classic的自动化所做的假设不再有效。 对于我们来说，目标是将必要的必需品聚集在一起，以进行良好的部署。 这采取了全副武装的方法来充实所有必要的细节。

Microsoft in recent releases of ASP.NET Core has added support for MS Build. Given the time frame, we were a bit too early for this announcement. One idea is review deployment requirements before you delve into ASP.NET Core. Investigate which part of your existing pipeline is reusable.

Microsoft在ASP.NET Core的最新版本中增加了对MS Build的支持 。 考虑到时间表，我们宣布此消息还为时过早。 一种想法是在深入研究ASP.NET Core 之前检查部署要求。 研究现有管道的哪一部分是可重用的。

The situation on IIS is much the same: there are plenty of changes. Windows Server and IIS need a new module for ASP.NET Core apps to work. A good solution is to isolate ASP.NET Core apps from classic legacy apps. The HTTP module necessary may have a negative impact on ASP.NET classic. On a live server, make sure you apply latest patches and have time to sort out any issues while the server is down. There are guides to get you started with setting up ASP.NET Core in IIS.

IIS的情况大致相同：有很多更改。 Windows Server和IIS需要一个新模块才能使ASP.NET Core应用程序正常工作。 一个好的解决方案是将ASP.NET Core应用程序与经典的旧版应用程序隔离。 必需的HTTP模块可能会对ASP.NET classic产生负面影响。 在实时服务器上，请确保您应用了最新的补丁程序，并有时间在服务器关闭时有时间解决所有问题。 有一些指南可帮助您开始在IIS中设置ASP.NET Core。

Now that the Fat Lady (ASP.NET Core) is happy and running, what other pitfalls are there?

既然Fat Lady(ASP.NET Core)很高兴并且可以运行，那么还有其他陷阱吗？

托管与非托管代码 (Managed Vs Unmanaged Code)

With automation, one common pitfall is to set the application pool to managed code. In ASP.NET Core, this is one piece of configuration you cannot reuse. One issue that kept cropping up during deployments was setting the app pool to the wrong mode. If you do so, you’ll see a process failure with a 502 error.

使用自动化，一个常见的陷阱是将应用程序池设置为托管代码。 在ASP.NET Core中，这是您不能重复使用的一项配置。 在部署期间不断出现的一个问题是将应用程序池设置为错误的模式。 如果这样做，您将看到进程失败并显示502错误。

What may cause confusion is that ASP.NET Core runs on top of the standard framework. ASP.NET classic, for example, runs on the classic framework and in managed code. In ASP.NET Core and IIS, the process that hosts your web application does not run on any framework. ASP.NET Core runs in a separate process, decoupled from the standard framework.

可能引起混乱的是ASP.NET Core在标准框架之上运行。 例如，ASP.NET classic在经典框架和托管代码中运行。 在ASP.NET Core和IIS中，承载Web应用程序的过程不在任何框架上运行。 ASP.NET Core在独立于标准框架的独立过程中运行。

Make sure you set the application pool to unmanaged code. When you double click the app pool, it should look like this:

确保将应用程序池设置为非托管代码。 双击应用程序池时，它应如下所示：

IIS runs ASP.NET Core apps as an external process through a reverse proxy. This is because it no longer has this tight integration with IIS and is cross-platform. The web server uses an HTTP module to track the process. ASP.NET Core has all the middleware necessary to send the HTTP response, it no longer depends on IIS.

IIS通过反向代理将ASP.NET Core应用程序作为外部进程运行。 这是因为它不再与IIS紧密集成，而是跨平台的。 Web服务器使用HTTP模块来跟踪该过程。 ASP.NET Core具有发送HTTP响应所需的所有中间件，而不再依赖IIS。

ASP.NET经典依赖项 (ASP.NET Classic Dependencies)

Any dependency that’s not on ASP.NET Core will have consequences. Inside your list of dependencies, you may find one that depends on ASP.NET classic. Anything that depends on ASP.NET classic needs the entire legacy framework for it to work.

任何不在ASP.NET Core上的依赖项都将导致后果。 在依赖项列表中，您可能会发现一个依赖于ASP.NET classic的依赖项。 任何依赖ASP.NET classic的东西都需要完整的旧框架才能运行。

Microsoft has made great strides towards making the transition seamless. For external popular dependencies, you’ll often find packages that work with ASP.NET Core. The ASP.NET Core framework has many of the same packages already familiar to you. This makes the upgrade a lot more practical and attainable.

微软在实现无缝过渡方面已取得了长足的进步。 对于外部流行的依赖关系，您经常会找到与ASP.NET Core兼容的软件包。 ASP.NET Core框架具有您已经熟悉的许多相同程序包。 这使升级更加实用和可实现。

For example, ASP.NET Core has packages for Entity Framework, Dapper, and ADO.NET. These packages are like their counterparts in ASP.NET classic.

例如，ASP.NET Core具有用于实体框架，Dapper和ADO.NET的程序包。 这些程序包就像它们在ASP.NET classic中的对应程序包一样。

With in-house dependencies, the situation is quite different. If the dependency doesn’t have an ASP.NET Core port, you’ll need ASP.NET classic. ASP.NET Core and ASP.NET classic are exclusive. This is often a blind spot for teams looking to move to the shiny new framework.

对于内部依赖性，情况就大不相同了。 如果依赖项没有ASP.NET Core端口，则需要ASP.NET classic。 ASP.NET Core和ASP.NET classic是互斥的。 对于希望转向闪亮的新框架的团队来说，这通常是一个盲点。

A good approach is to assess your list of dependencies and figure out what depends on what. Figure out your hierarchy of dependencies and drill into dependencies of a dependency. This way you know ahead of time what to expect. The idea is to cut surprises that behave in unpredictable ways during deployments.

一个好的方法是评估依赖项列表，并弄清什么取决于什么。 弄清您的依赖关系层次结构，并深入研究依赖关系。 这样，您可以提前知道会发生什么。 这样做的目的是减少在部署过程中以无法预测的方式表现出的意外情况。

If you still need ASP.NET classic because of dependencies, it is possible to run ASP.NET Core on the legacy framework. But, this adds more risk to your deployments, such as dealing with authentication cookies.

如果由于依赖性而仍需要ASP.NET Classic，则可以在旧框架上运行ASP.NET Core。 但是， 这给您的部署增加了更多风险 ，例如处理身份验证Cookie 。

One gotcha is that the default behavior you expect from dependencies will change. When wiring up ASP.NET Core dependencies, make sure you’re not making any assumptions. For example, the authentication cookie has a different set of default settings. ASP.NET Core is in some cases a complete rewrite, so a safe assumption is that default behaviors will change. Don’t make any of the same assumptions you made in ASP.NET classic. Test and verify all your dependencies.

一个陷阱是您期望依赖项的默认行为将发生变化。 连接ASP.NET Core依赖项时，请确保您没有做任何假设。 例如， 身份验证cookie具有一组不同的默认设置。 在某些情况下，ASP.NET Core是一个完整的重写，因此可以安全地假设默认行为会发生变化。 不要做与ASP.NET classic中相同的假设。 测试并验证所有依赖项。

结论 (Conclusion)

Overall, the new framework you get with ASP.NET Core is pretty slick. As a developer, you’ll find a better coding experience. The tooling streamlines the framework and it’s accessible from outside Visual Studio. Decoupling from Windows and IIS is a step in the right direction.

总体而言，ASP.NET Core提供的新框架非常漂亮。 作为开发人员，您会发现更好的编码体验。 该工具简化了框架，可以从Visual Studio外部进行访问。 与Windows和IIS脱钩是朝正确方向迈出的一步。

With ASP.NET Core, you’ll find a leaner framework with less cruft. I find the CLI tooling refreshing and very effective. For example, to run all unit tests, do dotnet test and get instant feedback in less than a second. There’s no need for clicking and getting frustrated in Visual Studio to get feedback. When you have a bunch of tests, the feedback in Visual Studio is often slow. The general coding experience is one that comes from a minimalist modern framework.

使用ASP.NET Core，您会发现精简的框架，减少了麻烦。 我发现CLI工具令人耳目一新，非常有效。 例如，要运行所有单元测试，请进行dotnet test并在不到一秒钟的时间内获得即时反馈。 无需在Visual Studio中单击并感到沮丧即可获得反馈。 当您进行大量测试时，Visual Studio中的反馈通常很慢。 一般的编码经验是来自极简主义的现代框架。

The ASP.NET Core MVC framework comes with improvements. Web API and MVC are now a single framework. You inherit from a single controller to use both. There’s no confusion in determining which one to use, which makes it more effective.

ASP.NET Core MVC框架进行了改进。 Web API和MVC现在是单个框架。 您从单个控制器继承以同时使用两者。 在确定要使用哪个选项时没有混淆，这使它更有效。

As with all new things, there are consequences to diving right in headlong. I hope this article points out common pitfalls you’ll want at least to consider. Best to know what you’re getting yourself into before embarking on this new adventure.

与所有新事物一样，彻底跳水会带来后果。 我希望本文指出您至少要考虑的常见陷阱。 踏上这项新冒险之旅之前，最好先了解一下自己要投入的工作。

SitePoint上的更多资源： (Further Resources on SitePoint:)

• Book: Build Your Own ASP.NET 4 Website Using C# & VB, 4th Edition (View an excerpt)

  书籍： 使用C＃和VB建立您自己的ASP.NET 4网站，第4版 (查看摘录 )

• Article: Build a Web Game in an Hour with Visual Studio and ASP.NET

  文章： 使用Visual Studio和ASP.NET在一个小时内构建网络游戏

翻译自: https://www.sitepoint.com/common-pitfalls-implementing-asp-net-core-apps/