Updating useRestrictiveXamlReader flag documentation and expectations

[dipeshmsft]

Summary

In this PR, I have updated the XamlReader document, especifically useRestrictiveXamlReader flags usage, capabilities and constraints. This is in alignment with the change here: dotnet/docs-desktop#2278

• Updated XamlReader's Load, LoadAsync and Parse method overload using useRestrictiveXamlReader flag.
• Added security remarks regarding the capabilities of the restrictive XAML reader mode in WPF.

---

Internal previews

File	Preview link
xml/System.Windows.Markup/XamlReader.xml	Preview published page

[Copilot]

Pull request overview

Updates WPF XamlReader documentation for restrictive-reader behavior, usage, and security expectations.

Changes:

• Documents useRestrictiveXamlReader across Load, LoadAsync, and Parse.
• Adds restrictive-mode security guidance.
• Expands parameter, return-value, and exception documentation.

Suppressed comments (2)

xml/System.Windows.Markup/XamlReader.xml:689

• This overload returns object, not a Task, and WPF completes the event-based load through LoadCompleted; the copied paragraph therefore describes behavior this API doesn't have. It also omits that the returned root can be populated later and that parsing is asynchronous only when the root contains x:SynchronousMode="Async" (otherwise the load is synchronous). Replace the task paragraph with the event-based async behavior documented by the sibling overload.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:System.Windows.Markup.XamlReader.Load(System.Xml.XmlReader,System.Boolean)" />.</remarks>

xml/System.Windows.Markup/XamlReader.xml:729

• This overload returns object, not a Task, and WPF completes the event-based load through LoadCompleted; the copied paragraph therefore describes behavior this API doesn't have. It also omits that the returned root can be populated later and that parsing is asynchronous only when the root contains x:SynchronousMode="Async" (otherwise the load is synchronous). Replace the task paragraph with the event-based async behavior documented by the sibling overload.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:System.Windows.Markup.XamlReader.Load(System.IO.Stream,System.Windows.Markup.ParserContext,System.Boolean)" />.</remarks>

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.