Chapter 27: Publishing and deploying your application

Introduction

This chapter introduction frames deployment as making an ASP.NET Core application accessible to users and previews hosting, IIS, Linux, and URL configuration.

• Deployment chapter scope: Explain that this chapter shifts from building application features to deploying an ASP.NET Core application so remote users can access it, covering hosting and deployment-related concerns.
  Why it matters: Deployment is what makes a completed application available beyond the development machine.
• Hosting and deployment roadmap: Describe the chapter's progression from the ASP.NET Core hosting model, reverse proxies, and the difference between dotnet run and publishing, through IIS and Linux deployment, to configuring application URLs with ASPNETCORE_URLS or command-line arguments.
  Why it matters: This roadmap helps you place each deployment choice and configuration task in the right part of the chapter.
• Legacy hosting model difference: State that ASP.NET Core's hosting model differs significantly from legacy ASP.NET on the .NET Framework, so developers with that background should not assume their previous hosting expectations apply.
  Why it matters: Recognizing this difference prevents legacy ASP.NET assumptions from obscuring how ASP.NET Core is deployed.

Key terms: deployment, hosting, remote server, ASP.NET Core hosting model, reverse proxy, dotnet run, publishing, IIS, ASPNETCORE_URLS, legacy ASP.NET

27.1 Understanding the ASP.NET Core hosting model

This section explains that ASP.NET Core apps are console processes hosting Kestrel and can be deployed directly or behind a reverse proxy, with resulting trade-offs.

• ASP.NET Core hosting model: Explain that an ASP.NET Core application is essentially a .NET console application with an entry point that runs a web server, typically Kestrel, inside its process. Describe how Kestrel receives HTTP requests, passes them to the application, and returns responses.
  Why it matters: This model explains what actually runs when an ASP.NET Core application is deployed.
• Reverse proxy deployment trade-offs: Describe a reverse proxy as internet-facing software that receives requests and forwards them to the underlying web server, which is exposed only to the proxy. Explain both the main benefits—security, caching performance, process management, and hosting multiple apps—and the costs of added complexity, inter-process communication, and possibly restricted features.
  Why it matters: Choosing whether and how to put an app behind a proxy affects its security, operations, performance, and available protocol features.

Key terms: hosting model, console application, static void Main, top-level statements, Kestrel, web server, reverse proxy, IIS, NGINX, Apache

27.1.1 Running vs. publishing an ASP.NET Core app

This section distinguishes development-time running from production publishing, explains how to run published output, and compares framework-dependent with self-contained deployments.

• Development CLI workflow: Describe the roles of dotnet new, restore, build, and run in the development workflow, and state that Visual Studio largely invokes the same underlying .NET CLI commands.
  Why it matters: Knowing the underlying CLI workflow helps you build and operate ASP.NET Core apps from any editor or platform.
• Build and publish outputs: Distinguish a build from a publish: dotnet build writes compiled artifacts, including the app DLL, to bin, whereas dotnet publish builds and packages everything needed for deployment into a publish folder. Explain that publishing copies static files such as wwwroot into the deployable output and should use the Release configuration for production.
  Why it matters: A successful local build is not by itself the complete set of files you should deploy to a production server.
• Published application execution: Explain that dotnet run is a development convenience command that locates a project, ensures it is built, finds its DLL, and runs it, whereas a published app is started with dotnet followed by the path to its application DLL, or equivalently dotnet exec. State that production only needs to run an already-built app, so this direct form starts faster.
  Why it matters: Servers must start the published application directly rather than expecting dotnet run to find a project file in the deployment folder.
• Deployment packaging models: Distinguish runtime-dependent deployments (RDDs) from self-contained deployments (SCDs). Explain that an RDD relies on an installed .NET 7 runtime and is smaller and portable across platforms, while an SCD packages its own runtime, must target a specific operating system and architecture, and isolates the app from the host runtime.
  Why it matters: The packaging model determines whether the target machine needs .NET installed, how large the deployment is, and who controls runtime updates.
• Runtime patch responsibility: Explain the update trade-off between deployment models: an RDD can receive host runtime patches without redeploying the app, whereas an SCD is an immutable snapshot with a fixed runtime, so its publisher must regularly republish it to apply runtime patches.
  Why it matters: Choosing a self-contained package gives you runtime control but also makes you responsible for keeping that bundled runtime patched.

Key terms: .NET CLI, dotnet new, dotnet restore, dotnet build, dotnet run, Visual Studio, bin folder, artifacts, dotnet publish, publish folder

27.1.2 Choosing a deployment method for your application

This section compares manual, automated, and Visual Studio-based deployment approaches and sets the chapter’s focus on deploying an ASP.NET Core app alongside legacy apps on IIS.

• Production deployment requirements: State the two fundamental requirements for deploying an application to production: a server that can run the app and a way to load the app onto that server.
  Why it matters: Every deployment choice must provide both somewhere to run the application and a way to get the application there.
• Deployment automation choices: Describe how CI/CD can detect version-control changes and automatically build and potentially deploy an application with little or no human intervention. Distinguish this automated approach from a traditional process where an operations team installs an application on a requested server or virtual machine.
  Why it matters: Automation can make releases more repeatable and less dependent on manual handoffs.
• Visual Studio publishing scope: Describe the built-in Visual Studio publishing options available through Build > Publish <AppName>, including that they can publish directly to multiple destinations. Explain why they are useful for getting started but a more automated and controlled approach is recommended for a larger application or team.
  Why it matters: Visual Studio publishing offers a simple starting point while highlighting when a team should move toward a managed release process.

Key terms: production, server, deploy, continuous integration, continuous delivery, continuous deployment, CI/CD, version control, Git, Visual Studio

27.2 Publishing your app to IIS

This section introduces the basic IIS setup and application preparation needed to deploy a published ASP.NET Core app on Windows behind IIS as a reverse proxy.

• IIS reverse proxy role: Explain that, for an ASP.NET Core application deployed on Windows, IIS commonly acts as the reverse proxy and manages the application in production.
  Why it matters: Knowing IIS's role helps you understand why an ASP.NET Core app needs IIS-specific deployment configuration.
• Basic IIS deployment setup: Describe the high-level IIS deployment work: create an application pool and website, configure the app to work behind IIS, publish it, and copy the published output to IIS's hosting folder.
  Why it matters: These are the basic moving parts that turn a published ASP.NET Core application into one hosted by IIS.
• Local IIS availability: State that developers who want to try the IIS steps locally on Windows may need to enable IIS manually on their development machine.
  Why it matters: You cannot test the local IIS deployment steps until IIS is available on the development machine.

Key terms: IIS, reverse proxy, ASP.NET Core, production, application pool, website, published app, hosting folder, Windows, development machine

27.2.1 Configuring IIS for ASP.NET Core

This section prepares IIS to host an ASP.NET Core application by installing the Windows Hosting Bundle, configuring an unmanaged application pool and website, and granting the pool access to the publish folder.

• Windows Hosting Bundle components: Explain why IIS hosting requires the ASP.NET Core Windows Hosting Bundle and name its key components: the .NET Runtime, ASP.NET Core Runtime, and IIS AspNetCore Module. State that the module links IIS to the app so IIS can operate as a reverse proxy, and that it is needed even for self-contained deployments.
  Why it matters: Without the hosting bundle and its IIS module, IIS cannot correctly start and proxy requests to an ASP.NET Core app.
• Unmanaged IIS application pool: Describe an IIS application pool as an application process that can isolate one IIS app from another, and explain how to create one for ASP.NET Core with its .NET CLR version set to No Managed Code. Explain that the native ASP.NET Core Module runs in this pool and starts the .NET 7 Runtime, rather than the app running in a managed .NET Framework pool.
  Why it matters: Using a No Managed Code pool matches how IIS hosts modern ASP.NET Core applications and keeps separate applications isolated.
• IIS website and folder permissions: Describe how to add an IIS website by supplying a site name and the future publish-folder path, assigning the No Managed Code application pool, and configuring bindings such as hostname or port. State that the app pool identity must be granted access to the publish folder using IIS AppPool\<pool name>, such as IIS AppPool\dotnet7.
  Why it matters: IIS needs both a correctly bound website and file-system access under its application-pool identity to serve the deployed application.

Key terms: ASP.NET Core Windows Hosting Bundle, .NET Runtime, ASP.NET Core Runtime, IIS AspNetCore Module, reverse proxy, self-contained deployment, application pool, No Managed Code, .NET CLR version, native ASP.NET Core Module

27.2.2 Preparing and publishing your application to IIS

This section explains how to prepare an ASP.NET Core application for IIS hosting and publish its files for deployment behind IIS as a reverse proxy.

• IIS integration setup: Describe when an ASP.NET Core application needs IIS integration and how to add it when using a custom application builder. Explain that WebApplicationBuilder adds IIS integration automatically.
  Why it matters: IIS must be able to communicate with the ASP.NET Core app in order to proxy requests and responses correctly.
• IIS hosting model selection: Distinguish IIS in-process hosting from out-of-process hosting and state which IIS integration extension corresponds to each model. Explain why using both extensions is safe when the production hosting model is not known in advance.
  Why it matters: The selected IIS hosting model determines how the application is hosted and which integration configuration becomes active.
• IIS request integration: Explain the main IIS integration behaviors: configuring the internal URL IIS forwards to, handling forwarded request headers as client information, and enabling Windows authentication when needed.
  Why it matters: These settings allow an application behind IIS to receive proxied requests as though they originated from the actual client.
• web.config publishing requirements: Describe why a published IIS application needs a web.config file and how publishing handles it. State that an existing project file is copied, while the publish command generates one when none exists, which is preferred when no customization is needed.
  Why it matters: A correct web.config configures IIS for the application and helps avoid broken behavior or accidentally exposed files.
• Published folder deployment: Trace the final IIS deployment flow: publish the application to a folder, copy the published files to the physical path configured in IIS, and browse to the IIS URL to verify the application.
  Why it matters: Publishing alone does not make the app available through IIS; IIS must point at the deployed publish output and be verified at its configured URL.

Key terms: IIS integration, WebApplicationBuilder, UseIIS(), UseIISIntegration(), custom application builder, in-process hosting model, out-of-process hosting model, IIS process, forwarded headers, Windows authentication

27.3 Hosting an application in Linux

This section introduces why ASP.NET Core can be hosted on Linux and frames the following material as a high-level deployment overview rather than detailed Linux configuration guidance.

• Linux deployment opportunities: Describe how ASP.NET Core's cross-platform support allows an application developed for Windows, Linux, or macOS to be deployed on Linux, including potentially cheaper cloud hosting, small devices such as Raspberry Pi, and Docker containers.
  Why it matters: Linux hosting expands the environments in which you can run an ASP.NET Core application.
• Linux hosting overview scope: Explain that Linux is highly configurable, which can be daunting for developers accustomed to Windows tools, and that this section emphasizes broad deployment steps and external resources instead of exhaustive configuration details.
  Why it matters: Knowing the intended level of detail helps you use the overview as a guide while consulting platform-specific resources for configuration.

Key terms: cross-platform, Linux, Raspberry Pi, Docker containers, configuration, resources

27.3.1 Running an ASP.NET Core app behind a reverse proxy in Linux

This section explains how to deploy an ASP.NET Core application on Linux by separating publishing, reverse-proxying, and process-management responsibilities.

• Linux deployment workflow: Describe the basic workflow for deploying an ASP.NET Core app to Linux: publish it, install its required runtime and prerequisites, copy the published files to the server, configure a reverse proxy, and configure process management.
  Why it matters: A Linux deployment needs more than copying application files: the application must be runnable, reachable, and kept alive.
• Reverse proxy and process manager: Explain why Linux commonly uses a reverse proxy and a separate process manager for an ASP.NET Core app. Distinguish forwarding internet requests from monitoring and restarting an application that crashes or stops responding.
  Why it matters: Separating traffic handling from application supervision is a central operational difference between Linux hosting and IIS hosting.
• Distributed proxy topology: Describe the common Linux topology in which the reverse proxy can run on a different server from the ASP.NET Core app, forwarding requests across to it. Explain why that separation means the proxy cannot be relied on to restart the app process.
  Why it matters: Recognizing that the proxy may be remote clarifies why application health supervision must be handled separately.
• Container deployment supervision: Explain how Docker containers make deployments repeatable by packaging an operating system, the app, and its dependencies, and state that container health is typically monitored by an orchestrator such as Kubernetes rather than by the reverse proxy.
  Why it matters: Containers can make the same application artifact portable across machines and cloud services, but they require an appropriate health-management approach.

Key terms: dotnet publish, RDD, SCD, runtime identifier, .NET 7 Runtime, reverse proxy, process manager, IIS, systemd, NGINX

27.3.2 Preparing your app for deployment to Linux

This section explains how to make an ASP.NET Core app behave correctly behind a Linux reverse proxy and avoid common Windows-to-Linux deployment pitfalls.

• Forwarded request information: Explain why a reverse proxy can hide the original client IP address and HTTPS scheme from an ASP.NET Core app, and how forwarded headers preserve that information.
  Why it matters: Your app can otherwise treat an HTTPS request as HTTP or identify the proxy rather than the real client.
• Forwarded headers middleware setup: Describe how ForwardedHeadersMiddleware makes HttpContext request properties, including Request.Scheme, reflect forwarded headers, and how to enable or add it correctly.
  Why it matters: Correcting request properties early prevents later middleware from making decisions based on the proxy-facing request instead of the original one.
• Linux portability considerations: Describe the Linux deployment differences that can affect an ASP.NET Core app, especially portable file paths and environment-variable configuration.
  Why it matters: Avoiding platform assumptions prevents failures that appear only after a Windows-developed app is deployed to Linux.

Key terms: reverse proxy, SSL/TLS offloading, X-Forwarded-For, X-Forwarded-Proto, Request.Scheme, HttpContext, ForwardedHeadersMiddleware, ASPNETCORE_FORWARDEDHEADERS_ENABLED, WebApplicationBuilder, generic host

27.4 Configuring the URLs for your application

This section explains when ASP.NET Core URL bindings must be configured and how to configure them with environment variables or command-line arguments.

• Reverse proxy URL handling: Explain why an application behind IIS does not normally need to configure its own listening URLs. Distinguish the external hostname configured in IIS from the internal URL IIS dynamically uses to forward requests to the app.
  Why it matters: This helps you avoid configuring application URL bindings unnecessarily when IIS is acting as the reverse proxy.
• ASPNETCORE_URLS URL binding: Describe how the ASPNETCORE_URLS environment variable changes the URLs on which an ASP.NET Core application listens. Explain the default localhost:5000 binding, semicolon-separated multiple URLs, and the difference between localhost and a wildcard port binding.
  Why it matters: Correct URL bindings determine whether an app can receive only local requests or requests from outside the machine.
• Binding precedence and hostnames: Explain that launchSettings.json takes precedence over ASPNETCORE_URLS when it is present, and that ASP.NET Core generally listens on all hostnames for a selected port rather than on a specific domain name. State the localhost exception.
  Why it matters: These details help diagnose an apparently ignored URL setting and prevent incorrect assumptions about domain-specific bindings.
• Per-application command-line URLs: Describe using the --urls command-line argument to set a particular application's listening URL when starting it, and explain why this is useful for multiple apps running side by side on one machine. State that --environment can likewise set the hosting environment and that command-line values override configuration values.
  Why it matters: Command-line URL configuration lets separately hosted applications use different ports without changing a machine-wide environment variable.
• Direct-hosting host filtering: State why an ASP.NET Core application exposed without a reverse proxy should use host filtering: it should respond only to hostnames the application expects.
  Why it matters: Host filtering adds a security check when Kestrel is directly reachable by clients.

Key terms: IIS, reverse proxy, ASP.NET Core Module, hostname, ASPNETCORE_URLS, localhost, http://localhost:5000, http://*:5002, environment variable, launchSettings.json

27.5 Summary

This summary recaps how ASP.NET Core apps are published, hosted behind IIS or reverse proxies, and configured to listen on URLs in production.