To make this easier, Azure App Service for Linux now includes Site Status. Site Status provides runtime information for your website, including the current state of the app and detailed error information when issues are detected.

What Site Status shows

Site Status gives you a view into the current runtime state of your App Service for Linux website.

You can see the site runtime status from the web app’s Properties experience. If the platform detects an issue with the site, the runtime status will show Issues Detected.

Selecting Issues Detected opens a detailed view where you can see the current status of the site, the last known error, and additional troubleshooting details. If your app is scaled out across multiple instances, Site Status shows this information for each instance hosting your app.

This makes it easier to answer questions such as:

• Is my website still starting?
• Did my website start successfully?
• Is the site stopped or blocked?
• Is the app recycling to apply changes?
• What was the last known runtime error?
• Is this likely a transient issue, or does the error point to a configuration problem?

Site Status values

Site Status reports one of the following platform-defined runtime states for your website:

These statuses provide a quick summary of the current or last known runtime state of your website.

View detailed issue information

When Site Status detects an issue, you can select Issues Detected to view more detailed runtime information.

The details page shows information such as:

For example, the screenshot above show a site that failed because the configured storage could not be mounted. The message points you toward the likely root cause. In this case, the issue is probably not with the site process itself. Restarting the app or replacing the instance may not resolve the problem. You would likely need to review the storage account, file share, firewall, networking, private endpoint, or authentication configuration.

Repair actions

From the issue details view, you can select Repair to take an action for the affected instance.

Available repair actions include:

These actions can be useful when your website has run into a transient runtime issue, or when the underlying instance is in a bad state.

However, repair actions are not a substitute for fixing configuration issues. For example, if the site cannot access a configured storage account because of network or authentication settings, restarting or replacing the instance is unlikely to fix the issue. The underlying configuration must be corrected first.

Site Status vs. Health Check

Site Status and Health Check are both useful for understanding and improving the reliability of App Service for Linux websites, but they serve different purposes.

Site Status helps you understand the current runtime state of your website. It provides platform-defined status values and detailed error information to help you troubleshoot startup, runtime, and configuration-related issues.

Health Check helps determine whether an instance should continue receiving traffic. It pings a customer-configured endpoint and uses the HTTP response to identify unhealthy instances, redirect traffic, and replace instances when needed.

Summary

Site Status gives you a clearer view into the runtime state of your App Service for Linux website. By surfacing platform-defined site status values and detailed runtime information, it helps you understand what is happening with your application as it starts, runs, updates, or stops.

We are continuously improving App Service for Linux to provide better visibility, more actionable information, and a smoother experience for running your applications in Azure.

Azure App Service on Linux is a fully managed platform for web and API applications across Python, Node.js, .NET, PHP, Java, and other stacks. Developers can deploy source code or a pre-built artifact, and App Service handles dependency installation, containerization, and running the application at cloud scale.

As more customers build intelligent applications with Azure AI Foundry and other AI services, Python has become one of the most important languages for these workloads. The performance and reliability of the Python deployment pipeline directly affect the developer experience on App Service, so we looked across the deployment path for opportunities to reduce latency and improve reliability.

The first set of changes has reduced Python deployment latency on Azure App Service on Linux by approximately 30%. This is the first step in a broader effort to make the platform better suited for AI application development, and the same improvements benefit many other Python apps on the platform.

Where deployment time was going

Python web application deployments on Azure App Service on Linux rely on Oryx, the platform’s open-source build system, to produce runnable artifacts during remote builds. Platform telemetry showed that about 70% of Python app deployments use remote builds, and most of those deployments resolve dependencies from requirements.txt by using pip install.

To understand where time was going, we profiled a stress workload: a 7.5 GB PyTorch application. Most production builds are smaller, but stress testing a dependency-heavy application made the pipeline bottlenecks clear.

When a Python app is deployed through remote build, the Kudu build container runs Oryx to:

1. Extract the uploaded source code.
2. Create a Python virtual environment.
3. Install dependencies with pip install; 4.35 minutes, or about 34% of build time.
4. Copy files to a staging directory; 0.98 minutes, or about 8% of build time.
5. Compress the output with tar and gzip into an archive; 7.53 minutes, or about 58% of build time.
6. Write the archive to /home, which is backed by an Azure Storage SMB mount.

The app container then extracts this archive to local disk on every cold start.

Why the archive-based approach?

The /home directory is backed by an Azure Storage SMB mount, where small-file I/O is comparatively expensive. Python dependencies are file-heavy. Virtual environments commonly contain tens of thousands of files, and dependency-heavy machine learning applications can exceed 200,000 files.

Writing those files individually over SMB would be prohibitively slow. Instead, the pipeline builds on the container’s local filesystem, writes a single compressed archive over SMB, and lets the app container extract it locally on startup for efficient module loading.

The key insight from profiling was that compression was the single largest phase at 58% of build time, taking longer than installing the packages themselves.

What changed

Zstandard compression replacing gzip

Standard gzip compression is single-threaded. In our benchmark, compression accounted for 58% of total build time, making it the dominant bottleneck. Because the archive is also decompressed during container startup, decompression time affects runtime startup latency as well.

We evaluated three compression algorithms: gzip, LZ4, and Zstandard (zstd). These results are averaged across multiple deployments of a 7.5 GB Python application with PyTorch and additional machine learning packages.

Both zstd and LZ4 were more than 6x faster than gzip for compression and more than 2x faster for decompression. We selected zstd because it provides speed comparable to LZ4 with a smaller archive size, is based on RFC 8878, ships with many common Linux distributions, and works natively with tar -I zstd without extra packages.

Result: compression time dropped from 7.53 minutes to 1.18 minutes, a 6.4x improvement. Decompression improved from 2.80 minutes to 1.07 minutes, a 2.6x improvement that directly reduces cold-start latency.

Faster package installation with uv

pip is implemented in Python and has historically optimized compatibility over maximum parallelism. In dependency-heavy workloads, package download, resolution, and installation can become a major part of deployment time. In the 7.5 GB PyTorch benchmark, package installation accounted for about 34% of total build time: 4.35 minutes out of 12.86 minutes.

We introduced uv, a Python package manager written in Rust, as the primary installer for compatible requirements.txt deployments. Its uv pip install interface works with standard pip workflows.

Compatibility remains the priority. When uv cannot handle a deployment, the platform retries with pip, preserving the behavior customers already depend on.

Package caches remain local to the build container. When the same app is deployed again before the Kudu build container is recycled, both pip and uv can reuse cached packages and avoid repeated downloads.

Result: package installation time dropped from 4.35 minutes to 1.50 minutes, a 3x improvement.

Reducing file copy overhead

File copy overhead appeared in two places. First, before compression, the build process copied the entire build directory, including application code and Python packages, to a staging location. This existed historically as a safety measure to create a clean snapshot before tar reads the file tree, but the cost was high for the large number of files common in Python dependencies.

The fix was straightforward: create the tar archive directly from the build directory and skip the intermediate copy.

Second, for pre-built deployment scenarios, we replaced the legacy Kudu sync path with Linux-native rsync. This gives us a better optimized tool for large Linux file trees and reduces the overhead of moving files into the final deployment location. Because this path is used beyond Python, the improvement benefits pre-built apps across the broader App Service on Linux ecosystem.

Result: the 0.98-minute staging copy, or 8% of build time, was eliminated. This also reduced temporary disk usage and improved the remaining file sync path.

Pre-built Python wheels cache

We added a complementary optimization: a read-only cache of pre-built wheels for commonly used Python packages, selected using platform telemetry. The cache is mounted into the Kudu build container at runtime for Python workloads, allowing the installer to use local wheel artifacts before downloading packages externally.

When a matching wheel is available, the installer uses it directly and avoids a network fetch for that package. Cache misses fall back to the upstream registry, such as PyPI, as usual.

The cache is managed by the platform and kept up to date, so supported Python builds can use it without any app changes.

Combined results

Controlled benchmark: PyTorch 7.5 GB on P1mv3

The following benchmark was measured on the P1mv3 App Service tier. Values in the “After” column reflect the optimized pipeline with zstd compression, uv package installation, direct tar creation, and the pre-built wheels cache enabled together.

Production fleet: all Python Linux web apps

Production telemetry across Python deployments shows the impact of these changes: deployment latency decreased by approximately 30% after rollout.

The controlled benchmark shows a larger improvement, about 79%, because it exercises a dependency-heavy workload where package installation, file copy, and compression dominate total build time. Typical production apps are smaller and spend less time proportionally in those phases.

Beyond faster builds: reliability and runtime performance

Faster builds only help when deployment requests reliably reach a worker that is ready to build. We updated the primary deployment clients, including Azure CLI, GitHub Actions, and Azure DevOps Pipelines, to warm up Kudu before initiating deployments. Clients now issue a lightweight health-check request to the Kudu endpoint, helping ensure the deployment container is running and ready before the deployment begins.

Clients also preserve affinity to the warmed-up worker by using the ARR affinity cookie returned by the first request. This increases the chance that the deployment uses a worker where Kudu is already running and local package caches are already available from recent deployments.

Together, these client-side changes reduced deployment failures from transient infrastructure issues and helped the pipeline optimizations reach the build phase reliably.

Result: deployment failures caused by cold-start errors such as 502, 503, and 499 dropped by approximately 30%.

We also improved the default runtime configuration for Python apps using the platform-provided Gunicorn startup path. Previously, the platform defaulted to a single worker, leaving most CPU cores idle. Now, it follows Gunicorn’s recommended worker formula, fully using available cores on multi-core SKUs and delivering higher request throughput out of the box.

workers = (2 * NUM_CORES) + 1

Key takeaways

• Measure before optimizing. Platform telemetry showed that remote builds and requirements.txt-based installs were the dominant Python deployment paths, helping us focus on changes that benefit the most customers.
• Compression was the biggest bottleneck. In the dependency-heavy benchmark, archive compression took longer than package installation. Replacing gzip with zstd reduced build time and cold-start extraction time.
• File count matters. Python virtual environments can contain tens of thousands of files, and AI workloads can contain many more. Reducing unnecessary file copies and using Linux-native file sync helped lower overhead.
• Compatibility needs a fallback path. Introducing uv improved the common path, while falling back to pip preserved compatibility for apps that depend on existing Python packaging behavior.
• Deployment reliability is part of performance. Faster builds only help if deployment requests consistently reach a ready worker. Warm-up and worker affinity made the optimized path more reliable for customers.
• Runtime defaults matter too. Settings such as Gunicorn worker configuration affect how production apps perform after deployment is complete.

Together, these changes make Python deployments faster and more reliable while preserving compatibility through safe fallbacks. We will continue improving the platform to make Azure App Service faster, more reliable, and better suited for AI application development.

Previously, when you deployed a FastAPI application, you needed to configure a custom startup command so the app could run correctly with an ASGI server. This added an extra step to the deployment flow and could create friction, especially when getting started with FastAPI on App Service.

We have now added built-in detection logic that identifies FastAPI applications automatically and configures the appropriate startup behavior for you.

What changed

When you deploy a Python app, App Service now scans common entry point files such as:

main.py, app.py, application.py, server.py, asgi.py, api.py, index.py, and run.py

If one of these files imports FastAPI using from fastapi or import fastapi, App Service detects the app as a FastAPI application.

To avoid false positives, files that also import Flask are skipped during FastAPI detection.

How your app is started

When a FastAPI app is detected, App Service automatically starts the application using Gunicorn with the Uvicorn worker class:

gunicorn -k uvicorn_worker.UvicornWorker

This provides the ASGI support required by FastAPI applications.

Framework detection priority

If multiple framework indicators are present, App Service uses the following priority order:

Django > FastAPI > Flask

Django continues to take precedence when a wsgi.py file is found in a subdirectory.

What this means for you

When you deploy a FastAPI app to Azure App Service for Linux, you no longer need to configure a custom startup command in the supported runtime flow. Oryx detects the FastAPI app and configures the startup behavior automatically.

This removes an extra setup step and makes it easier to get your FastAPI app running on App Service.

Availability

This improvement is currently enabled for Python 3.14 and later. Support for additional Python versions will be enabled in an upcoming rollout.

For more details on deploying Python apps to App Service, see the Azure App Service Python quickstart documentation.

Previously, changing app settings or connection strings could trigger an immediate recycle of Kudu or SCM site. If an asynchronous deployment was already running, this could interrupt the deployment and lead to failures or retries.

With Deferred Kudu Recycle, App Service now reduces unnecessary interruptions while still ensuring deployment-critical changes take effect when they are needed.

How it works

On Linux App Service, Kudu powers deployment workflows such as ZIP deploy, Git-based deployments, and Oryx-based builds. When app settings or connection strings change, Kudu needs to recycle so the updated environment is available.

With Deferred Kudu Recycle:

• If the setting change is not deployment-critical, the Kudu recycle is deferred until the in-progress asynchronous deployment completes.
• If the setting change is deployment-critical, Kudu recycles immediately so the deployment pipeline uses the correct configuration.
• New deployments started after the setting change always use the updated environment.
• Synchronous deployments are not affected by this behavior.

The deferral window is up to 40 minutes. If the deployment does not complete within that window, the recycle proceeds and the deployment may be interrupted.

What counts as deployment-critical?

Some settings directly affect how App Service builds or deploys your application. Changes to these settings continue to trigger an immediate Kudu recycle.

Examples include settings and prefixes such as:

For these settings, an immediate recycle helps ensure the deployment pipeline runs with the correct configuration.

Custom deployment-critical settings

Most customers do not need to configure anything. The default list covers common Kudu and Oryx deployment settings.

However, if your build or deployment process depends on custom app settings, you can mark them as deployment-critical by using the following app setting:

WEBSITE_DEPLOYMENT_CRITICAL_APPSETTINGS

The value should be a semicolon-separated list of setting names or prefixes.

Example:

WEBSITE_DEPLOYMENT_CRITICAL_APPSETTINGS=NODE_VERSION;MY_BUILD_FLAG

After this is configured, changes to NODE_VERSION or MY_BUILD_FLAG will trigger an immediate Kudu recycle instead of being deferred.

Only add settings that your build or deployment process genuinely depends on. Adding unnecessary entries can increase the chance of interrupting an in-progress asynchronous deployment.

What this means for you

Deferred Kudu Recycle improves deployment resiliency by reducing interruptions caused by unrelated configuration changes.

For example, changing a non-critical setting such as an Application Insights instrumentation key or a custom runtime setting that does not affect the build process will no longer interrupt an asynchronous deployment that is already in progress.

At the same time, App Service continues to recycle Kudu immediately when deployment-critical settings change, ensuring build and deployment workflows use the right configuration.

No action required for most apps

This improvement is enabled by the platform. For most applications, no changes are required.

Only use WEBSITE_DEPLOYMENT_CRITICAL_APPSETTINGS if you have custom app settings that directly influence your build or deployment process. Otherwise, the default behavior should provide improved deployment resiliency without any additional configuration.

With this feature, you can choose how quickly your app moves to newly rolled-out runtime patches. This helps teams balance two common needs: staying current with the latest security and platform updates, while also having enough time to validate changes before adopting them.

Why this matters

Runtime patch updates are important because they include fixes, security updates, and platform improvements. However, some production applications need time to validate these updates before moving to the newest available patch.

Platform Release Channel gives you that flexibility.

You can choose to stay close to the latest patch updates, use the default balanced option, or stay on an extended channel that gives you more time before adopting newer patches.

How it works

You can configure the Platform release setting from the Stack settings section in the Azure portal.

The setting supports three values:

By default, apps are set to Standard. This gives you additional time to test the latest patch before your app moves to it.

Choose Latest when security and immediate access to the newest runtime patches are your priority. Choose Extended when your application needs more validation time before adopting newer patch versions.

How channels move forward

When a new runtime patch is available, App Service first rolls it out through the Latest channel using a faster release cadence. The same patch then continues through the normal rollout process and becomes available in the Standard channel after it has progressed further through validation and rollout. Extended remains further behind Standard to provide additional validation time for apps that need it.

For example, with the current .NET 10 rollout, the channels look like this:

As the .NET 10 rollout progresses, the 10.0.7 patch will first be available through the Latest channel, then move to Standard through the normal rollout cadence.

For some stacks, Standard and Extended may currently show the same patch version. This is expected while the release channels are still moving through their rollout cadence. As additional rollout waves progress, the channel versions will separate and reflect the intended behavior for each channel.

Configure Platform Release Channel

You can configure it on the Azure portal

You can also configure the release channel using Azure CLI.

To move to the latest available patch channel:

az webapp update \
  --resource-group <resource-group> \
  --name <site-name> \
  --platform-release-channel Latest

To use the default channel:

az webapp update \
  --resource-group <resource-group> \
  --name <site-name> \
  --platform-release-channel Standard

To give your app more time before adopting newer patches:

az webapp update \
  --resource-group <resource-group> \
  --name <site-name> \
  --platform-release-channel Extended

Summary

Platform Release Channel gives you a simple way to control the pace at which runtime patch updates are applied to your Linux apps on Azure App Service.

Use Latest when you want the newest available patches as soon as they are rolled out. Use Standard for the default balance between currency and stability. Use Extended when your app needs more validation time before moving to newer runtime patches.

PHP 8.5 brings several useful runtime improvements. It includes better diagnostics, with fatal errors now providing a backtrace, which can make troubleshooting easier. It also adds the pipe operator (|>) for cleaner, more readable code, along with broader improvements in syntax, performance, and type safety. You can take advantage of these improvements while continuing to use the deployment and management experience you already know in App Service.

For the full list of features, deprecations, and migration notes, see the official PHP 8.5 release page: https://www.php.net/releases/8.5/en.php

Getting started

1. Create a PHP web app in Azure App Service
2. Configure a PHP app for Azure App Service

Introduction

Enterprises running ASP.NET Framework workloads on Windows Server with IIS face a familiar dilemma: modernize or stay put. The applications work, the infrastructure is stable, and nobody wants to be the person who breaks production during a cloud migration. But the cost of maintaining aging on-premises servers, patching Windows, and managing IIS keeps climbing.

Azure App Service has long been the lift-and-shift destination for these workloads. But what about applications that depend on Windows registry keys, COM components, SMTP relay, MSMQ queues, local file system access, or custom fonts? These OS-level dependencies have historically been migration blockers — forcing teams into expensive re-architecture or keeping them anchored to VMs.

Managed Instance on Azure App Service changes this equation entirely. And the IIS Migration MCP Server makes migration guided, intelligent, and safe — with AI agents that know what to ask, what to check, and what to generate at every step.

What Is Managed Instance on Azure App Service?

Managed Instance on App Service is Azure’s answer to applications that need OS-level customization beyond what standard App Service provides. It runs on the PremiumV4 (PV4) SKU with IsCustomMode=true, giving your app access to:

The key constraint: Managed Instance on App Service requires PV4 SKU with IsCustomMode=true. No other SKU combination supports it.

Why Managed Instance Matters for Legacy Apps

Consider a classic enterprise ASP.NET application that:

• Reads license keys from HKLM\SOFTWARE\MyApp in the Windows Registry
• Uses a COM component for PDF generation registered via regsvr32
• Sends email through a local SMTP relay
• Writes reports to D:\Reports\ on a local drive
• Uses a custom corporate font for PDF rendering

With standard App Service, you’d need to rewrite every one of these dependencies. With Managed Instance on App Service, you can:

• Map registry reads to Key Vault secrets via Registry Adapters
• Mount Azure Files as D:\ via Storage Adapters
• Enable SMTP Server via install.ps1
• Register the COM DLL via install.ps1 (regsvr32)
• Install the custom font via install.ps1

Zero application code changes required.

Note: When migrating your web applications to Managed Instance on Azure App Service, in the majority of use cases zero application code changes may be required — but depending on your specific web app, some code changes may be necessary.

Microsoft Learn Resources

• Managed Instance on App Service Overview
• Azure App Service Documentation
• App Service Migration Assistant Tool
• Migrate to Azure App Service
• Azure App Service Plans Overview
• PremiumV4 Pricing Tier
• Azure Key Vault
• Azure Files
• Azure Migrate application and code assessment for .NET
• Install Azure Migrate application and code assessment for .NET
• Interpret the analysis results

Why Agentic Migration? The Case for AI-Guided IIS Migration

The Problem with Traditional Migration

Microsoft provides excellent PowerShell scripts for IIS migration — Get-SiteReadiness.ps1, Get-SitePackage.ps1, Generate-MigrationSettings.ps1, and Invoke-SiteMigration.ps1. They’re free, well-tested, and reliable. So why wrap them in an AI-powered system?

Because the scripts are powerful but not intelligent. They execute what you tell them to. They don’t tell you what to do.

Here’s what a traditional migration looks like:

1. Run readiness checks — get a wall of JSON with cryptic check IDs like ContentSizeCheck, ConfigErrorCheck, GACCheck
2. Manually interpret 15+ readiness checks per site across dozens of sites
3. Decide whether each site needs Managed Instance or standard App Service (how?)
4. Figure out which dependencies need registry adapters vs. storage adapters vs. install.ps1 (the “Managed Instance provisioning split”)
5. Write the install.ps1 script by hand for each combination of OS features
6. Author ARM templates for adapter configurations (Key Vault references, storage mount specs, RBAC assignments)
7. Wire together PackageResults.json → MigrationSettings.json with correct Managed Instance fields (Tier=PremiumV4, IsCustomMode=true)
8. Hope you didn’t misconfigure anything before deploying to Azure

Even experienced Azure engineers find this time-consuming, error-prone, and tedious — especially across a fleet of 20, 50, or 100+ IIS sites.

What Agentic Migration Changes

The IIS Migration MCP Server introduces an AI orchestration layer that transforms this manual grind into a guided conversation:

The core value proposition: the AI knows the Managed Instance provisioning split. It knows that registry access needs an ARM template with Key Vault-backed adapters, while SMTP needs an install.ps1 section enabling the Windows SMTP Server feature. You don’t need to know this. The system detects it from your IIS configuration and source code analysis, then generates exactly the right artifacts.

Human-in-the-Loop Safety

Agentic doesn’t mean autonomous. The system has explicit gates:

• Phase 1 → Phase 2: “Do you want to assess these sites, or skip to packaging?”
• Phase 3: “Here’s my recommendation — Managed Instance for Site A (COM + Registry), standard for Site B. Agree?”
• Phase 4: “Review MigrationSettings.json before proceeding”
• Phase 5: “This will create billable Azure resources. Type ‘yes’ to confirm”

The AI accelerates the workflow; the human retains control over every decision.

Architecture: How the MCP Server Works

The system is built on the Model Context Protocol (MCP), an open protocol that lets AI assistants like GitHub Copilot, Claude, or Cursor call external tools through a standardized interface.

┌──────────────────────────────────────────────────────────────────┐
│  VS Code + Copilot Chat                                          │
│    @iis-migrate orchestrator agent                               │
│      ├── iis-discover   (Phase 1)                                │
│      ├── iis-assess     (Phase 2)                                │
│      ├── iis-recommend  (Phase 3)                                │
│      ├── iis-deploy-plan (Phase 4)                               │
│      └── iis-execute    (Phase 5)                                │
└─────────────┬────────────────────────────────────────────────────┘
              │  stdio JSON-RPC (MCP Transport)
              ▼
┌──────────────────────────────────────────────────────────────────┐
│  FastMCP Server (server.py)                                      │
│    13 Python Tool Modules (tools/*.py)                           │
│      └── ps_runner.py (Python → PowerShell bridge)               │
│            └── Downloaded PowerShell Scripts (user-configured)    │
│                  ├── Local IIS (discovery, packaging)            │
│                  └── Azure ARM API (deployment)                  │
└──────────────────────────────────────────────────────────────────┘

The server exposes 13 MCP tools organized across 5 phases, orchestrated by 6 Copilot agents (1 orchestrator + 5 specialist subagents).

Important: The PowerShell migration scripts are not included in this repository. Users must download them from GitHub and configure the path using the configure_scripts_path tool. This ensures you always use the latest version of Microsoft’s scripts, avoiding version mismatch issues.

The 13 MCP Tools: Complete Reference

Phase 0 — Setup

configure_scripts_path

Purpose: Point the server to Microsoft’s downloaded migration PowerShell scripts.

Before any migration work, you need to download the scripts from GitHub, unzip them, and tell the server where they are.

"Configure scripts path to C:\MigrationScripts"

Phase 1 — Discovery

1. discover_iis_sites

Purpose: Scan the local IIS server and run readiness checks on every web site.

This is the entry point for every migration. It calls Get-SiteReadiness.ps1 under the hood, which:

• Enumerates all IIS web sites, application pools, bindings, and virtual directories
• Runs 15 readiness checks per site (config errors, HTTPS bindings, non-HTTP protocols, TCP ports, location tags, app pool settings, app pool identity, virtual directories, content size, global modules, ISAPI filters, authentication, framework version, connection strings, and more)
• Detects source code artifacts (.sln, .csproj, .cs, .vb) near site physical paths

Output: ReadinessResults.json with per-site status: | Status | Meaning | |——–|———| | READY | No issues detected — clear for migration | | READY_WITH_WARNINGS | Minor issues that won’t block migration | | READY_WITH_ISSUES | Non-fatal issues that need attention | | BLOCKED | Fatal issues (e.g., content > 2GB) — cannot migrate as-is |

Requires: Administrator privileges, IIS installed.

2. choose_assessment_mode

Purpose: Route each discovered site into the appropriate next step.

After discovery, you decide the path for each site:

• assess_all: Run detailed assessment on all non-blocked sites
• package_and_migrate: Skip assessment, proceed directly to packaging (for sites you already know well)

The tool classifies each site into one of five actions:

• assess_config_only — IIS/web.config analysis
• assess_config_and_source — Config + source code analysis (when source is detected)
• package — Skip to packaging
• blocked — Fatal errors, cannot proceed
• skip — User chose to exclude

Phase 2 — Assessment

3. assess_site_readiness

Purpose: Get a detailed, human-readable readiness assessment for a specific site.

Takes the raw readiness data from Phase 1 and enriches each check with:

• Title: Plain-English name (e.g., “Global Assembly Cache (GAC) Dependencies”)
• Description: What the check found and why it matters
• Recommendation: Specific guidance on how to resolve the issue
• Category: Grouping (Configuration, Security, Compatibility)
• Documentation Link: Microsoft Learn URL for further reading

This enrichment comes from WebAppCheckResources.resx, an XML resource file that maps check IDs to detailed metadata. Without this tool, you’d see GACCheck: FAIL — with it, you see the full context.

Output: Overall status, enriched failed/warning checks, framework version, pipeline mode, binding details.

4. assess_source_code

Purpose: Analyze an Azure Migrate application and code assessment for .NET JSON report to identify Managed Instance-relevant source code dependencies.

If your application has source code and you’ve run the assessment tool against it, this tool parses the results and maps findings to migration actions:

The tool matches rules from the assessment output against known Managed Instance-relevant patterns. For a complete list of rules and categories, see Interpret the analysis results.

Output: Issues categorized as mandatory/optional/potential, plus install_script_features and adapter_features lists that feed directly into Phase 3 tools.

Phase 3 — Recommendation & Provisioning

5. suggest_migration_approach

Purpose: Recommend the right migration tool/approach for the scenario.

This is a routing tool that considers:

• Source code available? → Recommend the App Modernization MCP server for code-level changes
• No source code? → Recommend this IIS Migration MCP (lift-and-shift)
• OS customization needed? → Highlight Managed Instance on App Service as the target

6. recommend_target

Purpose: Recommend the Azure deployment target for each site based on all assessment data.

This is the intelligence center of the system. It analyzes config assessments and source code findings to recommend:

Each recommendation comes with:

• Confidence: high or medium
• Reasoning: Full explanation of why this target was chosen
• Managed Instance reasons: Specific dependencies that require Managed Instance
• Blockers: Issues that prevent migration entirely
• install_script_features: What the install.ps1 needs to enable
• adapter_features: What the ARM template needs to configure
• Provisioning guidance: Step-by-step instructions for what to do next

7. generate_install_script

Purpose: Generate an install.ps1 PowerShell script for OS-level feature enablement on Managed Instance.

This handles the OS-level side of the Managed Instance provisioning split. It generates a startup script that includes sections for:

The script can auto-detect needed features from config and source assessments, or you can specify them manually.

8. generate_adapter_arm_template

Purpose: Generate an ARM template for Managed Instance registry and storage adapters.

This handles the platform-level side of the Managed Instance provisioning split. It generates a deployable ARM template that configures:

Registry Adapters (Key Vault-backed):

• Map Windows Registry paths (e.g., HKLM\SOFTWARE\MyApp\LicenseKey) to Key Vault secrets
• Your application reads the registry as before; Managed Instance redirects the read to Key Vault transparently

Storage Adapters (three types): | Type | Description | Credentials | |——|————-|————-| | AzureFiles | Mount Azure Files SMB share as a drive letter | Storage account key in Key Vault | | Custom | Mount storage over private endpoint via VNET | Requires VNET integration | | LocalStorage | Allocate local SSD on the Managed Instance as a drive letter | None needed |

The template also includes:

• Managed Identity configuration
• RBAC role assignments guidance (Key Vault Secrets User, Storage File Data SMB Share Contributor, etc.)
• Deployment CLI commands ready to copy-paste

Phase 4 — Deployment Planning & Packaging

9. plan_deployment

Purpose: Plan the Azure App Service deployment — plans, SKUs, site assignments.

Collects your Azure details (subscription, resource group, region) and creates a validated deployment plan:

• Assigns sites to App Service Plans
• Enforces PV4 + IsCustomMode=true for Managed Instance — won’t let you accidentally use the wrong SKU
• Supports single_plan (all sites on one plan) or multi_plan (separate plans)
• Optionally queries Azure for existing Managed Instance plans you can reuse

10. package_site

Purpose: Package IIS site content into ZIP files for deployment.

Calls Get-SitePackage.ps1 to:

• Compress site binaries + web.config into deployment-ready ZIPs
• Optionally inject install.ps1 into the package (so it deploys alongside the app)
• Handle sites with non-fatal issues (configurable)

Size limit: 2 GB per site (enforced by System.IO.Compression).

11. generate_migration_settings

Purpose: Create the MigrationSettings.json deployment configuration.

This is the final configuration artifact. It calls Generate-MigrationSettings.ps1 and then post-processes the output to inject Managed Instance-specific fields:

Important: The Managed Instance on App Service Plan is not automatically created by the migration tools. You must pre-create the App Service Plan (PV4 SKU with IsCustomMode=true) in the Azure portal or via CLI before generating migration settings. When running generate_migration_settings, provide the name of your existing Managed Instance plan so the settings file references it correctly.

{
  "AppServicePlan": "mi-plan-eastus",
  "Tier": "PremiumV4",
  "IsCustomMode": true,
  "InstallScriptPath": "install.ps1",
  "Region": "eastus",
  "Sites": [
    {
      "IISSiteName": "MyLegacyApp",
      "AzureSiteName": "mylegacyapp-azure",
      "SitePackagePath": "packagedsites/MyLegacyApp_Content.zip"
    }
  ]
}

Phase 5 — Execution

12. confirm_migration

Purpose: Present a full migration summary and require explicit human confirmation.

Before touching Azure, this tool displays:

• Total plans and sites to be created
• SKU and pricing tier per plan
• Whether Managed Instance is configured
• Cost warning for PV4 pricing
• Resource group, region, and subscription details

Nothing proceeds until the user explicitly confirms.

13. migrate_sites

Purpose: Deploy everything to Azure App Service. This creates billable resources.

Calls Invoke-SiteMigration.ps1, which:

1. Sets Azure subscription context
2. Creates/validates resource groups
3. Creates App Service Plans (PV4 with IsCustomMode for Managed Instance)
4. Creates Web Apps
5. Configures .NET version, 32-bit mode, pipeline mode from the original IIS settings
6. Sets up virtual directories and applications
7. Disables basic authentication (FTP + SCM) for security
8. Deploys ZIP packages via Azure REST API

Output: MigrationResults.json with per-site Azure URLs, Resource IDs, and deployment status.

The 6 Copilot Agents

The MCP tools are orchestrated by a team of specialized Copilot agents — each responsible for a specific phase of the migration lifecycle.

@iis-migrate — The Orchestrator

The root agent that guides the entire migration. It:

• Tracks progress across all 5 phases using a todo list
• Delegates work to specialist subagents
• Gates between phases — asks before transitioning
• Enforces the Managed Instance constraint (PV4 + IsCustomMode) at every decision point
• Never skips the Phase 5 confirmation gate

Usage: Open Copilot Chat and type @iis-migrate I want to migrate my IIS applications to Azure

iis-discover — Discovery Specialist

Handles Phase 1. Runs discover_iis_sites, presents a summary table of all sites with their readiness status, and asks whether to assess or skip to packaging. Returns readiness_results_path and per-site routing plans.

iis-assess — Assessment Specialist

Handles Phase 2. Runs assess_site_readiness for every site, and assess_source_code when source code assessment results are available. Merges findings, highlights Managed Instance-relevant issues, and produces the adapter/install features lists that drive Phase 3.

iis-recommend — Recommendation Specialist

Handles Phase 3. Runs recommend_target for each site, then conditionally generates install.ps1 and ARM adapter templates. Presents all recommendations with confidence levels and reasoning, and allows you to edit generated artifacts.

iis-deploy-plan — Deployment Planning Specialist

Handles Phase 4. Collects Azure details, runs plan_deployment, package_site, and generate_migration_settings. Validates Managed Instance configuration, allows review and editing of MigrationSettings.json. Does not execute migration.

iis-execute — Execution Specialist

Handles Phase 5 only. Runs confirm_migration to present the final summary, then only proceeds with migrate_sites after receiving explicit “yes” confirmation. Reports results with Azure URLs and deployment status.

The Managed Instance Provisioning Split: A Critical Concept

One of the most important ideas Managed Instance introduces is the provisioning split — the division of OS dependencies into two categories that are configured through different mechanisms:

┌──────────────────────────────────────────────────────────────┐
│            MANAGED INSTANCE PROVISIONING SPLIT                │
├─────────────────────────────┬────────────────────────────────┤
│  ARM Template               │  install.ps1                   │
│  (Platform-Level)           │  (OS-Level)                    │
├─────────────────────────────┼────────────────────────────────┤
│  Registry Adapters          │  COM/MSI Registration          │
│    → Key Vault secrets      │    → regsvr32, RegAsm, msiexec │
│                             │                                │
│  Storage Mounts             │  SMTP Server Feature           │
│    → Azure Files            │    → Install-WindowsFeature    │
│    → Local SSD              │                                │
│    → VNET private storage   │  MSMQ                          │
│                             │    → Message queue setup        │
│                             │                                │
│                             │  Crystal Reports Runtime       │
│                             │    → SAP MSI installer          │
│                             │                                │
│                             │  Custom Fonts                  │
│                             │    → Copy to C:\Windows\Fonts  │
└─────────────────────────────┴────────────────────────────────┘

The MCP server handles this split automatically:

• assess_source_code detects which dependencies fall into which category
• recommend_target reports both adapter_features and install_script_features
• generate_adapter_arm_template builds the ARM template for platform features
• generate_install_script builds the PowerShell startup script for OS features

You don’t need to remember which goes where — the system decides and generates the right artifacts.

End-to-End Walkthrough: From Discovery to Running on Managed Instance

Here’s what a complete migration conversation looks like:

You: “@iis-migrate I want to migrate my IIS applications to Azure”

Phase 1 — Discovery:

Agent runs discover_iis_sites, presents a table:

Site	Status	Framework	Source Code?
HRPortal	READY_WITH_ISSUES	v4.8	Yes (.sln found)
PayrollAPI	READY	v4.8	No
IntranetCMS	BLOCKED (>2GB)	v4.7.2	No

Phase 2 — Assessment:

Agent runs assess_site_readiness for HRPortal — finds GACCheck and RegistryCheck failures. Runs assess_source_code using source code assessment report — confirms COM interop, registry access, and SMTP usage.

Phase 3 — Recommendation:

Agent runs recommend_target:

• HRPortal → MI_AppService (high confidence) — COM, registry, SMTP dependencies
• PayrollAPI → AppService (high confidence) — no OS dependencies

Generates install.ps1 for HRPortal (SMTP + COM sections). Generates ARM template with registry adapter (Key Vault-backed) for HRPortal.

Phase 4 — Deployment Planning:

Agent collects subscription/RG/region, validates PV4 availability. Packages both sites. Generates MigrationSettings.json with two plans:

• mi-plan-hrportal (PremiumV4, IsCustomMode=true) — HRPortal
• std-plan-payrollapi (PremiumV2) — PayrollAPI

Phase 5 — Execution:

Agent shows full summary with cost projection. You type “yes”. Sites deploy. You get Azure URLs within minutes.

Prerequisites & Setup

Quick Start

# Clone and set up the MCP server
git clone https://github.com/<your-org>/iis-migration-mcp.git
cd iis-migration-mcp
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Download Microsoft's migration scripts (NOT included in this repo)
# From: https://appmigration.microsoft.com/api/download/psscripts/AppServiceMigrationScripts.zip
# Unzip to C:\MigrationScripts (or your preferred path)

# Start using in VS Code with Copilot
# 1. Copy .vscode/mcp.json.example → .vscode/mcp.json
# 2. Open folder in VS Code
# 3. In Copilot Chat: "Configure scripts path to C:\MigrationScripts"
# 4. Then: @iis-migrate "Discover my IIS sites"

The server also works with any MCP-compatible client — Claude Desktop, Cursor, Copilot CLI, or custom integrations — via stdio transport.

Data Flow & Artifacts

Every phase produces JSON artifacts that chain into the next phase:

Phase 1: discover_iis_sites ──→ ReadinessResults.json
                                      │
Phase 2: assess_site_readiness ◄──────┘
         assess_source_code ───→ Assessment JSONs
                                      │
Phase 3: recommend_target ◄───────────┘
         generate_install_script ──→ install.ps1
         generate_adapter_arm ─────→ mi-adapters-template.json
                                      │
Phase 4: package_site ────────────→ PackageResults.json + site ZIPs
         generate_migration_settings → MigrationSettings.json
                                      │
Phase 5: confirm_migration ◄──────────┘
         migrate_sites ───────────→ MigrationResults.json
                                      │
                                      ▼
                              Apps live on Azure
                              *.azurewebsites.net

Each artifact is inspectable, editable, and auditable — providing a complete record of what was assessed, recommended, and deployed.

Error Handling

The MCP server classifies errors into actionable categories:

Conclusion

The IIS Migration MCP Server turns what used to be a multi-week, expert-driven project into a guided conversation. It combines Microsoft’s battle-tested migration PowerShell scripts with AI orchestration that understands the nuances of Managed Instance on App Service — the provisioning split, the PV4 constraint, the adapter configurations, and the OS-level customizations.

Whether you’re migrating 1 site or 10, agentic migration reduces risk, eliminates guesswork, and produces auditable artifacts at every step. The human stays in control; the AI handles the complexity.

Get started: Download the migration scripts, set up the MCP server, and ask @iis-migrate to discover your IIS sites. The agents will take it from there.

This project is compatible with any MCP-enabled client: VS Code GitHub Copilot, Claude Desktop, Cursor, and more. The intelligence travels with the server, not the client.

To get started, go to the Kudu/SCM site for your app:

<sitename>.scm.azurewebsites.net

From there, open the new Deployments experience.

You can now deploy your app by simply dragging and dropping a zip file containing your code. Once your file is uploaded, App Service shows you the contents of the zip so you can quickly verify what you’re about to deploy.

If your application is already built and ready to run, you also have the option to skip server-side build. Otherwise, App Service can handle the build step for you.

When you’re ready, select Deploy.

From there, the deployment starts right away, and you can follow each phase of the process as it happens. The experience shows clear progress through upload, build, and deployment, along with deployment logs to help you understand what’s happening behind the scenes.

After the deployment succeeds, you can also view runtime logs, which makes it easier to confirm that your app has started successfully.

This experience is ideal if you’re getting started with Azure App Service and want the quickest path from code to a running app. For production workloads and teams with established release processes, you’ll typically continue using an automated CI/CD pipeline (for example, GitHub Actions or Azure DevOps) for repeatable deployments.

We’re continuing to improve the developer experience on App Service for Linux. Give it a try and let us know what you think.

Recent Investments

Premium v4 (Pv4)

Azure App Service Premium v4 delivers higher performance and scalability on newer Azure infrastructure while preserving the fully managed PaaS experience developers rely on.

Premium v4 offers expanded CPU and memory options, improved price-performance, and continued support for App Service capabilities such as deployment slots, integrated monitoring, and availability zone resiliency.

These improvements help teams modernize and scale demanding workloads without taking on additional operational complexity.

App Service Managed Instance

App Service Managed Instance extends the App Service model to support Windows web applications that require deeper environment control. It enables plan-level isolation, optional private networking, and operating system customization while retaining managed scaling, patching, identity, and diagnostics. Managed Instance is designed to reduce migration friction for existing applications, allowing teams to move to a modern PaaS environment without code changes.

Faster Runtime and Language Support

Azure App Service continues to invest in keeping pace with modern application stacks. Regular updates across .NET, Node.js, Python, Java, and PHP help developers adopt new language versions and runtime improvements without managing underlying infrastructure.

Reliability and Availability Improvements

Ongoing investments in platform reliability and resiliency strengthen production confidence. Expanded Availability Zone support and related infrastructure improvements help applications achieve higher availability with more flexible configuration options as workloads scale.

Deployment Workflow Enhancements

Deployment workflows across Azure App Service continue to evolve, with ongoing improvements to GitHub Actions, Azure DevOps, and platform tooling. These enhancements reduce friction from build to production while preserving the managed App Service experience.

A Platform That Grows With You

These recent investments reflect a consistent direction for Azure App Service: active development focused on performance, reliability, and developer productivity. Improvements to runtimes, infrastructure, availability, and deployment workflows are designed to work together, so applications benefit from platform progress without needing to re-architect or change operating models.

The recent General Availability of Aspire on Azure App Service is another example of this direction. Developers building distributed .NET applications can now use the Aspire AppHost model to define, orchestrate, and deploy their services directly to App Service — bringing a code-first development experience to a fully managed platform.

We are also seeing many customers build and run AI-powered applications on Azure App Service, integrating models, agents, and intelligent features directly into their web apps and APIs. App Service continues to evolve to support these scenarios, providing a managed, scalable foundation that works seamlessly with Azure’s broader AI services and tooling.

Whether you are modernizing with Premium v4, migrating existing workloads using App Service Managed Instance, or running production applications at scale - including AI-enabled workloads - Azure App Service provides a predictable and transparent foundation that evolves alongside your applications.

Azure App Service continues to focus on long-term value through sustained investment in a managed platform developers can rely on as requirements grow, change, and increasingly incorporate AI.

Get Started

Ready to build on Azure App Service? Here are some resources to help you get started:

• Create your first web app — Deploy a web app in minutes using the Azure portal, CLI, or VS Code.
• App Service documentation — Explore guides, tutorials, and reference for the full platform.
• Aspire on Azure App Service — Now generally available. Deploy distributed .NET applications to App Service using the Aspire AppHost model.
• Pricing and plans — Compare tiers including Premium v4 and find the right fit for your workload.
• App Service on Azure Architecture Center — Reference architectures and best practices for production deployments.

Aspire brings a code-first model for building, running, and deploying distributed applications, with AppHost as the place where services, dependencies, and topology are declared. On Azure App Service, this means developers can keep the familiar Aspire programming model while using a fully managed platform for hosting, security patching and scaling. You can read more about the benefits of Aspire here.

If you’re new to Aspire on App Service, the fastest path is our Quickstart, which walks you through creating an Aspire starter app and deploying it to App Service

This release adds Deployment Slots support so you can adopt safer deployment patterns (staging → validate → swap). Here is a code snippet showing you how to add a slot.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureAppServiceEnvironment("<appsvc64>")
    .WithDeploymentSlot("dev");

var apiService = builder.AddProject<Projects.AspireApp64_ApiService>("apiservice")
    .WithHttpHealthCheck("/health")
    .WithExternalHttpEndpoints();

builder.AddProject<Projects.AspireApp64_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

1. If the production slot does not already exist, this creates both the production slot and the staging slot with identical code.
2. If the production slot already exists, the deployment goes only to the staging slot.

[NOTE]

Scaling: Manual scaling is supported (via AppHost code or the Azure portal), and you can also setup rule-based scaling. Automatic scaling is not yet supported in the current experience.

Learn more about the configuration options for Aspire on App Service here.

We’d love for you to try Aspire on App Service and tell us what you’re building - your feedback helps shape what we ship next.