ApplicationContentUriRules: what is it used for?


  • Hello guys.

    I've already asked this before, but I'm putting it in a new thread because this will probably make it easier to get an answer...

    According to the docs, this should be used for controlling this should be used for allowing or disallowing access to external urs. For instance, in the navigation quickstart, it said that this is necessary letting one load an external url in a iframe. So, I've built a new blank metro app and I've added the following in my default.html page:

     <div><a href="" target="frame">Navegar para homepage do jornal Record na iframe</a></div>
    <iframe name="frame"></iframe>

    And yes, I was able to load the external url in my local iframe. Notice that I didn't even add any entry to the ApplicationContentUriRules of the manifest. So, I've decided to run another experience: I've went ahead and modified that section so that it looks like this:

            <Rule Match="http://**" Type="exclude" />

    I expected this to block the iframe loading, but not, it simply loaded the page as before (notice that I've tried several URLS:, etc, etc, but never did the external url got blocked).

    So, what happens when you try to load the external ulr so that ir replaces the current page? To see what's going on, I've added the following anchor:

    <div><a href="">Navegar para homepage do jornal Record (substitui página atual)</a></div>

    ANd guess what? it opened metro ie and the site was loaded. this shouldn't happen according with the docs (some url as before):"You can also link to external pages—with some restrictions: you can display an external page in an iframe, but you can't navigate your top-level page to an external website."

     Since remote xmlhttprequests aren't influenced by the external content rules, I guess I'm a bit lost here. What is it used for? 


    Luis Abreu

    16 กุมภาพันธ์ 2555 12:49



  • Hi Luis,

    As far as the iframe example goes, I think that is simply a documentation bug.  I am checking and will get back to you.

    For your rules, please remove the wildcard * and retest.  (see the bottom of that article in the Community additions which also addressed these two issues).


    Jeff Sanders (MSFT)

    16 กุมภาพันธ์ 2555 15:29
  • Hello Jeff.

    I'm not sure if I understand. Are you saying that the URI section does influence what happens when I load the page? I'll come back with specific scenarios and results...

    Luis Abreu

    16 กุมภาพันธ์ 2555 15:45
  • I think there is an error in the documentation and I am checking to see if it is correct or not.

    Jeff Sanders (MSFT)

    16 กุมภาพันธ์ 2555 15:46
  • The documentation is incorrect and the behavior your are seeing is expected.  The rules apply to toplevel page navigation only and not frames.

    The team responsible for this page is aware of the problem, thanks for reporting it!


    Jeff Sanders (MSFT)

    16 กุมภาพันธ์ 2555 20:41
  • Hello again.

    Ok, so the info about iframes should be disregarded, right?

    So, what about top leve page navigation? The docs say it is not possible to navigate to an external page from your top level document. And that seems to be correct because when I tried to navigate to from a link which targetted the top page, it just opened the page in the browser.

    Now, back to the ApplicationContentUriRules section...

    What should happen when I add an the following to the manifest:

            <Rule Match="" Type="exclude" />

    And have an anchor which looks like this in the main page:

    <a href="">Go to Record</a>

    Should it open the page in the browser? In my machine, it is. I'm thinking that this section is only used for allowing external pages to access the WinJS library (haven't tested it yet). HOwever, there's a paragraph in the docs which makes me believe that I might be wrong:

    When you include a URI in your app's content, it can access your system's geolocation and media capture devices, as well as the clipboard (if your application has permission to access this functionality). It can also download files. Downloading an unknown file (such as a pdf file that cannot be handled by the application) redirects the user to the browser.

    Pages contained in your app's package are in the local context, and pages not included in your package (but included in your app's ApplicationContentUriRules) are in the web context.

    This last setence has really thrown me off, was I right in thinking that adding the url to the applicationcontenturirules is used so that the external page can access the windows runtime? (in that case, this last setence doesn't make sense). If not, can you please tell me what's the purpose of this ApplcationContentUriRules section?


    Luis Abreu

    17 กุมภาพันธ์ 2555 9:01
  • anyone? thanks.

    Luis Abreu

    20 กุมภาพันธ์ 2555 14:44
  • more pinging???

    Ok, I even thought it was related with allowing navigation from an external resource to a local resource, but nop, to achieve that, you need to call the addPublicLocalApplicationUri method...

    anyone? guys, I'm positive that someone can explain this to me...probably if I say please, please, please? :P

    Luis Abreu

    22 กุมภาพันธ์ 2555 14:34
  • Again,

    The documentation is not complete and has some incorrect information.  Stand by for updated documentation.

    Can you describe precisely what you are trying to accomplish and why you are blocked?  Then we can address your specific issue.  Providing complete documentation in the Forum would be a duplication of effort to update the documentation in the correct location (which is being worked on).


    Jeff Sanders (MSFT)

    22 กุมภาพันธ์ 2555 14:38
  • Hello again Jeff.

    Well, as I've said before, I'm currently evaluating the new WinJS library for building windows 8 metro apps (yes, this is part of my current daily activities). I'm only blocked because I'm trying to understand the purpose of the ApplicationContentUriRules. I don't need a definitive answer, only a clue on why  we have that section in the manifest...

    thanks again.

    Luis Abreu

    22 กุมภาพันธ์ 2555 14:50
  • OK cool, let's consider this closed then until there is an update to the documentation.

    Jeff Sanders (MSFT)

    22 กุมภาพันธ์ 2555 14:51
  • Ok Jeff.

    But, it better be well explained when we get the consumer preview bits (I believe this is what it is called now :)) by the end of this month..or else... I'll be here again asking about it :)

    thanks again.

    Luis Abreu

    22 กุมภาพันธ์ 2555 21:18
  • Yes, definately zap me if you do not see something after the CP!

    Jeff Sanders (MSFT)

    22 กุมภาพันธ์ 2555 21:30
  • Hello Jeff.

    [Edited after doing a little more digging]

    Consumer preview is out and I just want to be sure that I understand the docs. According to, a resource is in the local context if it placed inside the app's package and it's in the web context if it's not in the package *and* if it's added to the ApplicationContentUriSection. 

    So, two questions then:

    1. in what context does a page run when it's an external page and it's not in the applicationcontenturisection with an include type? Are there even more limitations in that *new* context when compared with the web context?

    [Partial answer: now, I'm almost positive that for an external page to run in the web content, it needs to be included in the ApplicationContentUriRules section. When that doesn't happen, the page does not run in the web context, but I still don't know if there's a name for that "remote" context. Btw, what are the limitations of that "remote" context? Still haven't found anything in the docs about it]

    2. what's the difference between a.) adding an external URI rule with an exclude type to the applicationcontenturirules and b.) not adding an external URI rule to that section?

    [I'm assuming that there's no difference between adding an exclude rule for an URI and not adding an entry for that URI. I'm also thinking that excluding might be useful when, for instance, you need to allow the pages on a domain to run in web context, while at the same time you don't want to allow pages in a subdomain to be ran in the web context]

    thank you.

    Luis Abreu

    2 มีนาคม 2555 9:37
  • Hi Luis,

    Apologies about the outdated documentation. The current state of the world looks like this:

    1. Only package content can run in the local context. Content from the web will be in the web context always.
    2. The top level document must be in the package. You cannot navigate the app frame itself to a webpage, you can only iframe a webpage.
    3. ApplicationContentUriRules are used only to grant access to specific resources that require a prompt, such as geolocation and clipboard access. This is to prevent you from accidentally iframing an untrusted page and the user thinking it is your app asking for geolocation info.
    4. I believe the only distinction between exclude and include for the rules is that exclude has higher precedence. This used to be important if you were able to navigate the app frame to a remote site, but wanted certain content on that site to open in the browser.

    Hopefully that clears things up a bit!



    5 มีนาคม 2555 23:33
  • Hello Jeff.

    Yes, what you're saying does confirm my tests. There's just one more thing I need to clear out before ending this thread: the use of the term  "web context". You say: "content from the web will be in the web context always". However, the docs say that Web context is for external pages added to the ApplicationContentURIRules (or local pages loaded with the ms-appx-web scheme).

    Notice that I'm only worried with the terminology because I understand the concepts (you've explained them quite well). Let me resume it:

    1.) local pages -> default context for package content

    2.) external pages added to the ApplicationContentUriRules with include rule -> runs in what the current online docs call web context (now I do understand that this will let me use some features like geo which won't be available if there's not an entry in this section)

    3.) external pages not added to the ApplicationContentUriRules -> not running in what the current online docs call web context

    So, what I need to know is if 2 and 3 are called web context (like  you pointed out in 1) or if 2 is called web context and we don't still have an official term for 3.


    Luis Abreu

    6 มีนาคม 2555 10:03
  • Hi Luis,

    The notion of "web context" and "local context" are actually completely separate from what is or isn't in ApplicationContentUriRules. The easiest way to tell what context you are in is to see if the "Windows" object (the root of all WinRT APIs) exists or not.

    The complication that ApplicationContentUriRules adds is that for script that is not part of your package, scripts matching the include rules get access to the above mentioned platform features (geoloc, clipboard.) If you forget to specify ApplicaitonContentUriRules, you will actually see error messages in the JS console when these APIs are used by web script under the debugger. Coincidentally, any script loaded from outside your package is considered to be in the web context. So yes, 2 and 3 are the same context, they just have slightly different behavior with respect to specific APIs.

    You are also correct that local pages default to being in the local context unless you specifically load them using the ms-appx-web scheme. So to summarize: http, https, and ms-appx-web means web context. Only ms-appx means local context. You can verify what scheme the current page is running under in the debugger by typing "window.location.href" into the JS console while at a breakpoint.

    Hopefully this clears everything up. I know it's a tad complicated at times, but hopefully it's also clear that the reason for this complexity is to protect your customers from malicious script on the web.



    6 มีนาคม 2555 23:55
  • Hello Jeff.

    Thanks for making it perfectly clear. I understand what you're saying and why you're doing it. My only problem is seeing that the docs have been updated from developer to consumer preview, but they are still wrong. Btw, I think I've sent the wrong link before. This is the one I was referring to:

    And here's the snippet which was responsible for my previous confusion:

    Adding an external page to your app's web context

    Pages contained in your app's package are in the local context, and pages not included in your package (but included in your app'sApplicationContentUriRules) are in the web context.

    As you can see, here web context is defined as "no included in the package, but included in applicationcontenturirules). I'll add a note to the wiki referencing this discussion, but probably some one should do something about that paragraph.

    Luis Abreu

    7 มีนาคม 2555 8:23
  • Yep, it's a documentation bug. I'm following up with our tech writers. Thanks for commenting on the page and for pointing this out!



    7 มีนาคม 2555 18:23