How to Configure IIS Deployment with Web Deploy on Windows Server 2025

February 6, 2026
Tutorials
Comment off

How to Configure IIS Deployment with Web Deploy on Windows Server 2025

Web Deploy (MSDeploy) is Microsoft’s official tool for synchronising web applications, databases, and IIS configurations between servers or from a developer workstation to a target environment. On Windows Server 2025, combining IIS with Web Deploy enables one-command deployments, CI/CD pipeline integration, and reliable rollbacks — eliminating the manual file copy workflows that cause environment drift. This guide covers installing Web Deploy on the target server with the correct delegation handler, setting up the IIS Management Service, deploying from the command line and from Visual Studio, generating Publish Profiles, using Web.config transformations, and wiring everything into an automated pipeline.

Prerequisites

Windows Server 2025 with the Web Server (IIS) role installed
IIS Management Console and IIS Management Service role services installed
Local administrator rights on the target server
Web Deploy 4.0 installer (webdeploy_amd64_en-US.msi) — download from the IIS.NET site or via the Web Platform Installer
On the developer or build machine: Visual Studio 2022+ or the Web Deploy command-line tools
TCP port 8172 open inbound on the target server firewall (Web Management Service port)

Step 1: Install IIS Management Service on the Target Server

The IIS Management Service must be installed before Web Deploy’s delegation handler can be configured. Open PowerShell as administrator:

# Install required IIS role services
Install-WindowsFeature -Name Web-Server, Web-Mgmt-Service, Web-Scripting-Tools `
  -IncludeManagementTools

# Confirm services are present
Get-WindowsFeature Web-Mgmt-Service

Enable and start the Web Management Service (WMSVC):

Set-Service -Name WMSVC -StartupType Automatic
Start-Service -Name WMSVC

# Verify it is listening on 8172
netstat -ano | Select-String ":8172"

Step 2: Allow Remote Connections in IIS Manager

Open IIS Manager, select the server node, and double-click Management Service. Check Enable remote connections, set the identity to Windows credentials only (or mixed if you use IIS Manager Users), and click Apply. Restart WMSVC after saving:

Restart-Service -Name WMSVC

Step 3: Install Web Deploy 4.0 on the Target Server

Download the MSI and install with the IIS Deployment Handler component — this is what enables remote deployments over port 8172 without requiring a full remote agent service accessible over port 80:

# Download Web Deploy 4.0
$wdUri = "https://download.microsoft.com/download/webdeploy_amd64_en-US.msi"
Invoke-WebRequest -Uri $wdUri -OutFile "C:Tempwebdeploy_amd64_en-US.msi"

# Install with all features including IIS Deployment Handler and delegation
msiexec.exe /i "C:Tempwebdeploy_amd64_en-US.msi" /qn `
  ADDLOCAL=ALL

After installation, verify the handler is registered in IIS:

# Confirm the MSDeploy handler exists
Get-WebHandler -PSPath "IIS:" | Where-Object { $_.Name -like "*Deploy*" }

Step 4: Configure Delegation Rules for Non-Administrator Deployment

To allow deployment using a non-admin IIS Manager user (best practice), open IIS Manager → Server node → Management Service Delegation. Add delegation rules for the following providers so the deploy user can manage them:

contentPath — maps to the web root
iisApp — application pool recycling and app management
appPoolConfig — application pool configuration
setAcl — sets file permissions on the web root

You can also configure this via PowerShell using the WebAdministration module:

Import-Module WebAdministration

# Grant deploy user access to contentPath provider on a specific site
Add-WebConfiguration -PSPath "MACHINE/WEBROOT/APPHOST" `
  -Filter "system.webServer/management/delegation/rule" `
  -Value @{
    providers = "contentPath,iisApp,setAcl"
    actions = "*"
    path = "C:inetpubwwwrootMyApp"
    identity = @{ logonMethod = "ClearText"; userName = "deployuser"; password = "P@ssw0rd!" }
  }

Step 5: Deploy from the Command Line with msdeploy.exe

From any machine that has Web Deploy tools installed, run msdeploy.exe to synchronise a local IIS application to the remote server. The binary is located at C:Program FilesIISMicrosoft Web Deploy V4msdeploy.exe:

# Sync local IIS app to remote server
& "C:Program FilesIISMicrosoft Web Deploy V4msdeploy.exe" `
  -verb:sync `
  -source:iisApp="Default Web Site/MyApp" `
  -dest:iisApp="Default Web Site/MyApp",`
    computerName="https://192.168.1.50:8172/msdeploy.axd",`
    userName="deployuser",`
    password="P@ssw0rd!",`
    authType="Basic" `
  -enableRule:AppOffline `
  -allowUntrusted

The -enableRule:AppOffline flag places a temporary App_Offline.htm file in the application root during deployment to gracefully handle in-flight requests. Remove -allowUntrusted once you have a valid TLS certificate on port 8172.

Step 6: Deploy from Visual Studio Using the Publish Dialog

In Visual Studio 2022, right-click the web project and select Publish. Choose Web Server (IIS) → Web Deploy and enter:

Server: 192.168.1.50
Site name: Default Web Site/MyApp
User name: deployuser
Password: (deploy user password)
Destination URL: http://192.168.1.50/MyApp

Visual Studio generates a .pubxml Publish Profile that can be committed to source control (without the password) and reused:

<!-- PropertiesPublishProfilesProduction.pubxml -->
<Project>
  <PropertyGroup>
    <WebPublishMethod>MSDeploy</WebPublishMethod>
    <PublishProvider>AzureWebSite</PublishProvider>
    <MSDeployServiceURL>192.168.1.50:8172</MSDeployServiceURL>
    <DeployIisAppPath>Default Web Site/MyApp</DeployIisAppPath>
    <SkipExtraFilesOnServer>True</SkipExtraFilesOnServer>
    <MSDeployPublishMethod>WMSVC</MSDeployPublishMethod>
    <EnableMSDeployBackup>False</EnableMSDeployBackup>
    <UserName>deployuser</UserName>
    <Configuration>Release</Configuration>
  </PropertyGroup>
</Project>

Step 7: Web.config Transformations

Web.config transformations replace environment-specific values at publish time. Create a Web.Release.config file alongside the base Web.config:

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <connectionStrings>
    <add name="DefaultConnection"
         connectionString="Server=prod-sql01;Database=MyAppDB;
           Integrated Security=True;TrustServerCertificate=True;"
         xdt:Transform="SetAttributes"
         xdt:Locator="Match(name)" />
  </connectionStrings>
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>
</configuration>

Step 8: Automated Deployment via CI/CD Pipeline

In a GitHub Actions or Azure DevOps pipeline, call msdeploy from a PowerShell step. Store the deploy password as a pipeline secret:

# GitHub Actions step example (windows-latest runner)
- name: Deploy to IIS via Web Deploy
  shell: pwsh
  run: |
    $msdeploy = "C:Program FilesIISMicrosoft Web Deploy V4msdeploy.exe"
    & $msdeploy `
      -verb:sync `
      -source:package="${{ github.workspace }}publishMyApp.zip" `
      -dest:iisApp="Default Web Site/MyApp",`
        computerName="https://${{ vars.DEPLOY_SERVER }}:8172/msdeploy.axd",`
        userName="${{ vars.DEPLOY_USER }}",`
        password="${{ secrets.DEPLOY_PASSWORD }}",`
        authType="Basic" `
      -enableRule:AppOffline `
      -setParam:name="IIS Web Application Name",value="Default Web Site/MyApp"

Build the deployment package beforehand with MSBuild:

dotnet publish MyApp.csproj `
  -c Release `
  -o publish `
  /p:DeployOnBuild=true `
  /p:WebPublishMethod=Package `
  /p:PackageAsSingleFile=true `
  /p:PackageLocation=publishMyApp.zip

Conclusion

You now have a complete Web Deploy pipeline on Windows Server 2025 — from a manually triggered Visual Studio publish to a fully automated CI/CD workflow. The IIS Management Service on port 8172 provides a secure, narrowly scoped deployment channel that does not require opening PowerShell Remoting or granting broad administrative access. For further hardening, replace self-signed certificates on WMSVC with a certificate from your internal CA, restrict delegation rules to specific site paths rather than the entire server, and consider implementing deployment slot logic using multiple IIS sites with a Network Load Balancer or ARR for zero-downtime releases.

Links

Newsletter

Contact