How to force the download of PDF documents using web.config

Using a simple IIS configuration file to change PDF MIME and content types and force the download of documents rather than have them open in the browser's built-in reader.

Introduction

A user recently reported an issue with some of the PDF forms on one of our websites. When a user fills out the PDF in Edge's built-in reader and saves the document locally, it would reset some of the inputs to their default values. After some back and forth, through trial and error we've decided to force the download of the documents locally and bypass the browser's built-in reader altogether.

Because this had to be implemented rather quickly, without any changes to IIS, I put together a small web.config to change the PDF MIME type and trigger a download.

Details

Normally, defining a new file extension is a straightforward process. However, because we're modifying an existing value that's probably already defined in the server's base configuration, we also need to break the root-level association.

MIME Type

The first thing we have to do is change the document's MIME type. MIME types are used to tell the browser how to identify and interpret files. In this case, we do not want it to use the standard PDF identifier (application/pdf) so we instead define PDF extensions as a generic data stream.

Before we can change our MIME type, we first have to remove the server's default configuration for the extension, which would superseed any local definitions.

<staticContent>
  <remove fileExtension=".pdf" />
  <mimeMap fileExtension=".pdf" mimeType="application/octet-stream" />
</staticContent>

Content Disposition

Decidedly, Edge doesn't care about document MIME types and instead elects to load PDF documents in its built in reader anyway. To get around this issue, we can change the server's response header so it comes up as an attachment, which triggers a download prompt in Edge.

Again, because the server normally has a default content-disposition defined, we need to remove it before adding ours.

<httpProtocol>
  <customHeaders>
    <remove name="Content-Disposition" />
    <add name="Content-Disposition" value="attachment" />
  </customHeaders>
</httpProtocol>

Solution

Save the following XML as web.config and simply copy to the desired directory. Note that by default, configuration files will only apply to the location they are currently in and will not propogate to child folders.

<configuration>
  <system.webServer>
    <staticContent>
      <remove fileExtension=".pdf" />
      <mimeMap fileExtension=".pdf" mimeType="application/octet-stream" />
    </staticContent>
    <httpProtocol>
      <customHeaders>
        <remove name="Content-Disposition" />
        <add name="Content-Disposition" value="attachment" />
      </customHeaders>
    </httpProtocol> 
  </system.webServer>
</configuration>

Conclusion

While not an ideal solution to the problem of PDF incompability, implementing a directory-based configuration is an easy way to work around a browser's built-in readers.