部署ASP.NET Core Web API到IIS的web.config问题排查及部署求助

Hey there! Let's break down how to troubleshoot web.config-related issues when deploying your ASP.NET Core Web API (built with VS2017's Web API template) to IIS. I’ve dealt with similar deployment headaches before, so here’s a step-by-step guide to help you identify and fix the problem:

Before diving into web.config, make sure your IIS setup is compatible with ASP.NET Core:

• Install the ASP.NET Core Hosting Bundle: This is non-negotiable—without it, IIS can’t forward requests to your .NET Core app. Ensure the bundle version matches your project’s .NET Core runtime (VS2017 typically targets .NET Core 2.x to 3.1, so grab the corresponding bundle).
• Check Application Pool Settings:
  • Set the Managed pipeline mode to No Managed Code (ASP.NET Core runs as a self-contained process; IIS acts as a reverse proxy, so it doesn’t need .NET Framework hosting).
  • Confirm the identity of the app pool has read/write access to your site’s root folder (especially if you’re enabling stdout logs later).

When you publish your project, VS generates a web.config automatically—but it’s easy for small mismatches to break things. Here’s what to check in your deployed web.config:

Example of a Correct Base web.config #

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\YourApiName.dll" 
                  stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" 
                  hostingModel="InProcess" />
    </system.webServer>
  </location>
</configuration>

Key Checks: #

• AspNetCoreModule Version: If you installed an older Hosting Bundle, replace AspNetCoreModuleV2 with AspNetCoreModule (but updating the bundle to the latest compatible version is better).
• processPath & arguments: Double-check that the DLL name matches your published project’s output (e.g., YourApiName.dll), and the path is relative to the web.config’s location (usually your IIS site’s root folder).
• Enable Stdout Logs (Temporarily): Set stdoutLogEnabled="true"—this creates a logs folder with detailed console output from your app. This is the single most useful tool for catching startup errors, missing dependencies, or third-party API call failures.
• Hosting Model: If InProcess mode is causing issues, switch to OutOfProcess (change hostingModel="OutOfProcess"). Some environments have compatibility issues with in-process hosting.

If your index.html isn’t loading, even though it worked in IIS Express:

• Confirm Static Files Middleware: In your project’s Startup.cs, ensure the Configure method includes app.UseStaticFiles();—this tells ASP.NET Core to serve files from wwwroot.
• IIS Default Document: In your IIS site settings, add index.html to the top of the Default Documents list. IIS won’t automatically serve it unless it’s in this list.
• Check Published Files: Verify the wwwroot folder (and all its contents) were copied to your IIS site’s root directory during publishing. Sometimes VS skips static files if publishing settings aren’t configured correctly—double-check your publish profile to ensure "Include all files in the project directory" is enabled.

If your frontend AJAX calls are failing after deployment:

• Route Paths: If you deployed to an IIS virtual directory (not a root site), your API routes will now be prefixed with the virtual directory name (e.g., /VirtualDir/api/your-endpoint instead of /api/your-endpoint). Update your frontend AJAX URLs to match, or reconfigure the IIS site to be a root application.
• Request Filtering: Check IIS’s Request Filtering settings to ensure it’s not blocking HTTP verbs (like POST/PUT) or specific API paths.
• CORS (If Needed): If your frontend is hosted on a different domain (unlikely for local company use, but possible), confirm your ASP.NET Core app has CORS middleware enabled and configured to allow the frontend’s origin.

If you’re still stuck, use these tools to get concrete error details:

• Stdout Logs: As mentioned earlier, the logs/stdout files will show exactly what’s going wrong when your app starts or processes requests—this includes exceptions from third-party API calls, missing NuGet packages, or configuration issues.
• Windows Event Viewer: Navigate to Windows Logs > Application and look for events tagged with ASP.NET Core or dotnet. These will show system-level errors (like failed process starts or permission issues).
• Temporary Detailed Errors: For debugging only, add environment="Development" to the <aspNetCore> node in web.config, or configure your app to show detailed error pages in the Startup.cs (don’t leave this enabled in production!).

内容的提问来源于stack exchange，提问作者Maggie