What does existingResponse="PassThrough" mean in IIS?

Question

The documentation says

existingResponse="PassThrough"

Leaves the response untouched if an existing response exists. http://www.iis.net/configreference/system.webserver/httperrors#005

But what does that mean by "existing response exists"?

E.g. I want my customErrors handler to suppress the ASP.NET response, so that IIS would think that response doesn't exist. How would I do that?

Solution

There are three possible values, from the schema:

<attribute name="existingResponse" type="enum" defaultValue="Auto">
  <enum name="Auto" value="0" />
  <enum name="Replace" value="1" />
  <enum name="PassThrough" value="2" />
</attribute>

Roughly, here is how I understand this:

PassThrough - leaves the existing response alone, as long as there is one. It is possible that your application logic doesn't return anything. In that case the error page defined here is used.

Auto - uses the IIS error pages as defined in this node except when in asp.net you did set:

Response.TrySkipIisCustomErrors = true;

if you've done that, the response from your code is used.

Replace - always uses the IIS error pages, even if the developer has set TrySkipIisCustomErrors.

The last option seems to be the one you want.

---

Edit:

Consider:

existingResponse="PassThrough"

now try to open a non-existing asp.net page, you'll see:

Even though the resource was not there, the runtime provided a response, it is passed through to the browser.

Now, try to open a non-existing html page. This time we still get a 404 status but an empty page.

changing to:

existingResponse="Auto"

the missing asp.net page still displays the asp.net error page, but for the missing html page we now get the IIS one:

So, summarizing: when looking at missing html and aspx pages with different existingResponse values, we get different error pages:

                .html-404   .aspx-404   .aspx-500
--------------------------------------------------
Auto             IIS         asp.net    asp.net
PassThrough      -           asp.net    asp.net
Replace          IIS         IIS        IIS

Comments

[Andrey Shchekin]

So how do I pretend there is no response from ASP.NET so that PassThrough uses an error page? I have tried calling Response.End without sending anything, but it didn't work.

[Andrey Shchekin]

The last option seems to be the one you want -- I only want to send IIS error page if there was no other response from ASP.NET, not instead of every response with error code.

[Peter Hahndorf]

@AndreyShchekin - in that case PassThrough seems to be the best option.

[Andrey Shchekin]

Maybe -- but what does "existing response" mean? How can I send an non-existing response in ASP.NET (while still sending a response code)? When I try to send an empty response IIS just passes it through as empty.

[Peter Hahndorf]

@AndreyShchekin - Remember this setting is not just for ASP.NET. I added some more detail to my answer.

[Andrey Shchekin]

Thanks. I think it basically demonstrates that documentation is incorrect, and PassThrough just never uses the IIS response. That's unfortunate. But fair enough, I'll have to use Auto then.