Add notes about untrusted data in System.Speech API docs (#12058)

* Add notes about untrusted data in System.Speech API docs

* Add back specific verbiage about URIs and DLLs

Co-authored-by: Copilot <[email protected]>

* Fix indentation of note

* Add back the blank line between paragraphs

* Improve wording to 'instance of this type'

---------

Co-authored-by: Copilot <[email protected]>

Author: jeffhandley

includes/untrusted-data-instance-note.md

@@ -1,2 +1,2 @@
 > [!IMPORTANT]
-> Using an instance of this object with untrusted data is a security risk. Use this object only with trusted data. For more information, see [Validate All Inputs](https://top10proactive.owasp.org/archive/2024/the-top-10/c3-validate-input-and-handle-exceptions/).
+> Using an instance of this type with untrusted data is a security risk. Use this object only with trusted data. For more information, see [Validate All Inputs](https://top10proactive.owasp.org/archive/2024/the-top-10/c3-validate-input-and-handle-exceptions/).

xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml

@@ -857,6 +857,8 @@ public void WorldSoccerWinners ()
 ## Remarks
  <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument.XmlBase%2A> property gets a value that is used to resolve relative URIs in a <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument> object. Suppose the value for <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument.XmlBase%2A> is `http://www.contoso.com/` and the <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument> contains a relative rule reference to another document, for example `SrgsRuleRef("ExternalGrammar.grxml")`. This creates the following absolute path to the external document: `http://www.contoso.com/ExternalGrammar.grxml`.
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
  ]]></format>
         </remarks>
       </Docs>

xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml

@@ -52,6 +52,8 @@
 
  This class represents the `ruleref` element as defined in the World Wide Web Consortium (W3C) [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761). For information about the SRGS `ruleref` element and details about its support by System.Speech, see [ruleref Element](https://msdn.microsoft.com/library/56eb0031-4908-4788-83ab-7c5e19aa4ac0).
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
  ]]></format>
     </remarks>
     <related type="Article" href="https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361680(v%3doffice.14)">Create Grammars Using SrgsGrammar</related>
@@ -211,7 +213,7 @@ public void WorldSoccerWinners ()
 
 -   <xref:System.Speech.Recognition.SrgsGrammar.SrgsRuleRef.%23ctor%2A>
 
-
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
 
 ## Examples
  The following example creates a grammar for an application that returns information about bus shuttle service. The first method, `GrammarUrlForRoute`, takes a string that specifies a route and appends it to a string specifying the location of a grammar. This specifies a particular rule in that grammar. The method returns a `Uri` for that rule.
@@ -407,6 +409,8 @@ namespace SampleRecognition
 
 -   <xref:System.Speech.Recognition.SrgsGrammar.SrgsRuleRef.%23ctor%2A>
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
@@ -497,6 +501,8 @@ namespace SampleRecognition
 
 -   <xref:System.Speech.Recognition.SrgsGrammar.SrgsRuleRef.%23ctor%2A>
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
@@ -546,6 +552,8 @@ namespace SampleRecognition
 
 -   <xref:System.Speech.Recognition.SrgsGrammar.SrgsRuleRef.%23ctor%2A>
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
  ]]></format>
         </remarks>
         <related type="Article" href="https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361680(v%3doffice.14)">Create Grammars Using SrgsGrammar</related>

xml/System.Speech.Recognition/Grammar.xml

@@ -45,9 +45,11 @@
 
  The grammar's <xref:System.Speech.Recognition.Grammar.SpeechRecognized> event is raised when input matches a path through the grammar.
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
 > [!NOTE]
->  It is a best practice to verify the safety of any URI or DLL used to build a <xref:System.Speech.Recognition.Grammar> object.
->
+>  It is a best practice to verify the safety of any URI or DLL used to build a <xref:System.Speech.Recognition.Grammar> object, which helps prevent security vulnerabilities when loading external resources.
+> 
 >  Windows and the Speech platform provide security for applications constructing a <xref:System.Speech.Recognition.Grammar> instance from a DLL or from a grammar that supports scripting.
 >
 >  Scripts in <xref:System.Speech.Recognition.Grammar> objects are always run as if downloaded from a web page in the `Internet Zone`. The Common Language Runtime (CLR) isolates any DLL loaded to obtain a grammar definition.
@@ -944,6 +946,7 @@ private static Grammar CreateGrammarFromFile2()
 
  This constructor does not validate `baseUri`. However, the `LoadGrammar` method of a <xref:System.Speech.Recognition.SpeechRecognitionEngine> or <xref:System.Speech.Recognition.SpeechRecognizer> object throws an exception if it cannot resolve all of the rule references in the grammar description. If `baseUri` is not `null`, the `LoadGrammar` method uses the URI to resolve any rule references that it cannot otherwise resolve. If `baseUri` represents a file, then the `LoadGrammar` uses both the designated file and the file's directory when it attempts to resolve relative rule references.
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
 
 
 ## Examples
@@ -1112,7 +1115,7 @@ private static Grammar CreateGrammarFromStream3()
 
  This constructor does not validate `baseUri`. However, the `LoadGrammar` method of a <xref:System.Speech.Recognition.SpeechRecognitionEngine> or <xref:System.Speech.Recognition.SpeechRecognizer> object throws an exception if it cannot resolve all of the rule references in the grammar description. If `baseUri` is not `null`, the `LoadGrammar` method uses the URI to resolve any rule references that it cannot otherwise resolve. If `baseUri` represents a file, then the `LoadGrammar` method uses both the designated file and the file's directory when it attempts to resolve relative rule references.
 
-
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
 
 ## Examples
  The following example creates a speech recognition grammar in an <xref:System.Speech.Recognition.SrgsGrammar.SrgsDocument> that contains a relative rule reference to the cities.xml file, and specifies a URI to use to resolve the rule reference. The content of the cities.xml file appears in the XML example that follows the C# example.
@@ -1276,6 +1279,8 @@ private static Grammar CreateSrgsDocumentGrammar3()
 ## Remarks
  Parameters for an initialization handler may also be specified.
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">-   Any of the parameters contain an invalid value.
@@ -1329,6 +1334,8 @@ private static Grammar CreateSrgsDocumentGrammar3()
 ## Remarks
  Parameters for an initialization handler may also be specified.
 
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentException">-   Any of the parameters contain an invalid value.

xml/System.Speech.Synthesis.TtsEngine/ITtsEngineSite.xml

@@ -179,7 +179,14 @@
         <param name="mediaType">The media type of the resource.</param>
         <summary>Loads the resource at the specified URI.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Remarks
+
+[!INCLUDE [untrusted-data-interface-note](~/includes/untrusted-data-interface-note.md)]
+
+]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Rate">

xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml

@@ -122,7 +122,7 @@
   
  The value of `mediaType` is typically a MIME specification, as the SSML specification uses MIME for media specifications.  
   
-   
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
   
 ## Examples  
  The implementation of <xref:System.Speech.Synthesis.TtsEngine.TtsEngineSsml.AddLexicon%2A> uses the <xref:System.Speech.Synthesis.TtsEngine.ITtsEngineSite> interface passed in to load a lexicon from a resource. It then stores a `System.IO.Stream` to the lexicon in a `System.Collections.Generic.Dictionary` instance, indexed by the lexicon URI.  
@@ -275,7 +275,7 @@ internal struct WaveFormat {
   
  This method is typically called in response to a <xref:System.Speech.Synthesis> based applications calling <xref:System.Speech.Synthesis.SpeechSynthesizer.RemoveLexicon%2A> and using the synthesizer voice implemented by the current <xref:System.Speech.Synthesis.TtsEngine.TtsEngineSsml> instance.  
   
-   
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
   
 ## Examples  
  The implementation of <xref:System.Speech.Synthesis.TtsEngine.TtsEngineSsml.RemoveLexicon%2A> uses the lexicon URI to query an instance `System.Collections.Generic.Dictionary` for the `System.IO.Stream`, closes the stream and removes the uri referring to the lexicon.  

xml/System.Speech.Synthesis/FilePrompt.xml

@@ -67,7 +67,8 @@
 ## Remarks  
  You can use this class to create an object from an existing Speech Synthesis Markup Language (SSML) file that the <xref:System.Speech.Synthesis.SpeechSynthesizer> can consume to generate speech.  
   
-   
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
   
 ## Examples  
  The example that follows creates a <xref:System.Speech.Synthesis.FilePrompt> object that specifies a path to an SSML prompt. To speak the contents of the prompt, the example then provides the <xref:System.Speech.Synthesis.FilePrompt> object as the argument to the <xref:System.Speech.Synthesis.SpeechSynthesizer.Speak%2A> method.  
@@ -150,7 +151,14 @@ namespace SampleSynthesis
         <param name="promptFile">The URI of the file containing the prompt content.</param>
         <param name="media">The media type of the file.</param>
         <summary>Creates a new instance of the <see cref="T:System.Speech.Synthesis.FilePrompt" /> class, and specifies the location of the file and its media type.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Remarks
+
+[!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)]
+
+ ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>

xml/System.Speech.Synthesis/PromptBuilder.xml

@@ -229,6 +229,8 @@ public void MySimpleText ()
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
+
 ## Examples
  The following example initializes a new instance of the <xref:System.Speech.Synthesis.PromptBuilder> class and then adds text to it, followed by an audio file.
 
@@ -291,6 +293,7 @@ public void SimpleConcatenation()
 ## Remarks
  The speech synthesis engine will speak the alternate text if the audio file cannot be played.
 
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
 
 
 ## Examples
@@ -874,6 +877,7 @@ namespace SampleSynthesis
 
  You can also append SSML markup as a string using <xref:System.Speech.Synthesis.PromptBuilder.AppendSsmlMarkup%2A>.
 
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
 
 
 ## Examples

xml/System.Speech.Synthesis/SpeechSynthesizer.xml

@@ -164,6 +164,7 @@ namespace SampleSynthesis
 
 - The value `application/vdn.ms-sapi-lex` indicates that the lexicon format is Uncompressed Lexicon, which is a Microsoft-proprietary format. This is a legacy format and we recommend that you use the PLS format described above.
 
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
 
 
 ## Examples
@@ -766,6 +767,8 @@ namespace SampleSynthesis
 ## Remarks
  See <xref:System.Speech.Synthesis.SpeechSynthesizer.AddLexicon%2A> for an example.
 
+[!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)]
+
  ]]></format>
         </remarks>
         <altmember cref="M:System.Speech.Synthesis.SpeechSynthesizer.AddLexicon(System.Uri,System.String)" />