In Azure App Service, developers often need to serve files (images, config files, data files, etc.) that are stored outside the app’s wwwroot folder — such as on an Azure File Share.
Background:
In Azure App Service, developers often need to serve files (images, config files, data files, etc.) that are stored outside the app’s wwwroot folder — such as on an Azure File Share.
This is especially useful when:
- You want to share files across multiple web apps
- Your files are too large to bundle with the app
- You need to manage files independently from the app deployment
To accomplish this, Azure provides the ability to:
- Mount external Azure File Shares into your web app's file system
- Expose those mounted folders via virtual paths
- Configure directory browsing and MIME types to make files directly accessible over the browser
Step-by-Step Configuration:
===Azure Storage Account part===
Create Azure File Share
===Azure App Service part===
1.Mount Azure File Share
Azure Portal → App Service → Configuration → Path Mappings → Mount Storage
- Click + New Azure Storage Mount
- Provide:
- Name: (e.g. fileshare)
- Storage account: Select your storage account
- Storage container: Select your file share name
- Mount Path: (e.g. /mounts/share)
The mounted path will appear as C:\mounts\share in the backend file system (Kudu).
2.Set Virtual Path to Expose via URL
Azure Portal → Configuration → Path Mappings → Virtual applications and directories
- Click + Add
- Virtual Path: e.g. /fileshare (URL access path)
- The Virtual Path is the URL path that users will type in the browser to access a folder or file hosted by your App Service.
- Physical Path: \mounts\share
- The Physical Path (Mount Path) is the actual folder path on the file system where your Azure File Share is located inside the App Service.
- Select Directory
This maps URL path (Virtual Path, like /files) to a specific physical folder (Physical Path, like C:\mounts\share).
3.Verify File Structure in Kudu
Open Kudu: https://<your-app-name>.scm.azurewebsites.net
Go to: Debug Console → CMD → C:\mounts\share
You should see your mounted file share contents (e.g., folders, .jpg, .json)
Common Issues & Fixes
Issue 1: Access Denied When Browsing Virtual Path
Example URL: https://<app>.azurewebsites.net/fileshare/
-> Showing directory listing
Error message from browser: You do not have permission to view this directory or page.
Cause: Directory browsing is disabled by default.
Solution: Create a web.config file under site\wwwroot with:
<configuration>
<system.webServer>
<directoryBrowse enabled="true" />
</system.webServer>
</configuration>
This enables directory listing in browser.
Issue 2: Can't open .json Files
Example URL: https://<app>.azurewebsites.net/fileshare/folder1/AppInit.json
-> Serving .json file correctly
Error message from browser: The resource you are looking for has been removed, had its name changed, or is temporarily unavailable.
Cause: MIME type for .json files is not configured.
Solution: Update web.config to allow serving .json:
<configuration>
<system.webServer>
<staticContent>
<mimeMap fileExtension=".json" mimeType="application/json" />
</staticContent>
</system.webServer>
</configuration>
Reference: Configure an App Service App - Azure App Service | Microsoft Learn
Published Apr 11, 2025
Version 1.0James_Yu320
Microsoft
Joined February 13, 2023
Apps on Azure Blog
Follow this blog board to get notified when there's new activity