mcs/class/corlib/Documentation/en/System.Runtime.InteropServices.WindowsRuntime/ReturnValueNameAttribute.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <Type Name="ReturnValueNameAttribute" FullName="System.Runtime.InteropServices.WindowsRuntime.ReturnValueNameAttribute">
   3   <TypeSignature Language="C#" Value="public sealed class ReturnValueNameAttribute : Attribute" />
   4   <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit ReturnValueNameAttribute extends System.Attribute" />
   5   <AssemblyInfo>
   6     <AssemblyName>mscorlib</AssemblyName>
   7     <AssemblyVersion>4.0.0.0</AssemblyVersion>
   8   </AssemblyInfo>
   9   <Base>
  10     <BaseTypeName>System.Attribute</BaseTypeName>
  11   </Base>
  12   <Interfaces />
  13   <Attributes>
  14     <Attribute>
  15       <AttributeName>System.AttributeUsage(System.AttributeTargets.Delegate | System.AttributeTargets.ReturnValue | System.AttributeTargets.All, AllowMultiple=false, Inherited=false)</AttributeName>
  16     </Attribute>
  17   </Attributes>
  18   <Docs>
  19     <remarks>
  20       <attribution license="cc4" from="Microsoft" modified="false" />
  21       <para>In a wrt component, all the parameters of a method and the return value must have names. By default, <format type="text/html"><a href="d2ce0683-343d-403e-bb8d-209186f7a19d">Winmdexp.exe (Windows Runtime Metadata Export Tool)</a></format> gives the return value the name "value". When you use a component in a win8_appname_long app written in JavaScript, you can use this name to retrieve the return value. For example, suppose a component defines a method that has a return value and two out parameters (ByRef parameters with the <see cref="T:System.Runtime.InteropServices.OutAttribute" /> attribute in Visual Basic):</para>
  22       <code>public static int ComputeAverage([ReadOnlyArray()] int[] input,
  23     out int minValue, out int maxValue)
  24 {
  25     …
  26 }
  27 </code>
  28       <code>Public Shared Function ComputeAverage( _
  29         &lt;ReadOnlyArray()&gt; ByVal input As Integer, _
  30         &lt;Out()&gt; ByRef minValue As Integer, _
  31         &lt;Out()&gt; ByRef maxValue As Integer) As Integer
  32     …
  33 End Function
  34 </code>
  35       <para>When you call the function from JavaScript, you can access the return value by its default name (value): </para>
  36       <code>    var data = [5, 13, 23, 37];
  37     var results = SampleComponent.TestStuff.computeAverage(data);
  38     var formattedResults = "Min=" + results.minValue + ", Avg=" +
  39         results.value + ", Max=" + results.maxValue;
  40 </code>
  41       <para>You must give the return value a different name if you already have a parameter named "value". Or you might simply want to use a more meaningful name (such as "average" in this example). Apply the <see cref="T:System.Runtime.InteropServices.WindowsRuntime.ReturnValueNameAttribute" /> attribute to your method and specify a new name. </para>
  42       <code>[return: ReturnValueName("average")]
  43 public static int ComputeAverage([ReadOnlyArray()] int[] input,
  44     out int minValue, out int maxValue)
  45 {
  46     …
  47 }
  48 </code>
  49       <code>Public Shared Function ComputeAverage( _
  50         &lt;ReadOnlyArray()&gt; ByVal input As Integer, _
  51         &lt;Out()&gt; ByRef minValue As Integer, _
  52         &lt;Out()&gt; ByRef maxValue As Integer) _
  53             As &lt;ReturnValueName("average")&gt; Integer
  54     …
  55 End Function
  56 </code>
  57     </remarks>
  58     <summary>
  59       <attribution license="cc4" from="Microsoft" modified="false" />
  60       <para>Specifies the name of the return value of a method in a wrt component.</para>
  61     </summary>
  62   </Docs>
  63   <Members>
  64     <Member MemberName=".ctor">
  65       <MemberSignature Language="C#" Value="public ReturnValueNameAttribute (string name);" />
  66       <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string name) cil managed" />
  67       <MemberType>Constructor</MemberType>
  68       <AssemblyInfo>
  69         <AssemblyVersion>4.0.0.0</AssemblyVersion>
  70       </AssemblyInfo>
  71       <Parameters>
  72         <Parameter Name="name" Type="System.String" />
  73       </Parameters>
  74       <Docs>
  75         <remarks>To be added.</remarks>
  76         <summary>
  77           <attribution license="cc4" from="Microsoft" modified="false" />
  78           <para>Initializes a new instance of the <see cref="T:System.Runtime.InteropServices.WindowsRuntime.ReturnValueNameAttribute" /> class, and specifies the name of the return value.</para>
  79         </summary>
  80         <param name="name">
  81           <attribution license="cc4" from="Microsoft" modified="false" />The name of the return value. </param>
  82       </Docs>
  83     </Member>
  84     <Member MemberName="Name">
  85       <MemberSignature Language="C#" Value="public string Name { get; }" />
  86       <MemberSignature Language="ILAsm" Value=".property instance string Name" />
  87       <MemberType>Property</MemberType>
  88       <AssemblyInfo>
  89         <AssemblyVersion>4.0.0.0</AssemblyVersion>
  90       </AssemblyInfo>
  91       <ReturnValue>
  92         <ReturnType>System.String</ReturnType>
  93       </ReturnValue>
  94       <Docs>
  95         <value>To be added.</value>
  96         <remarks>To be added.</remarks>
  97         <summary>
  98           <attribution license="cc4" from="Microsoft" modified="false" />
  99           <para>Gets the name that was specified for the return value of a method in a wrt component.</para>
 100         </summary>
 101       </Docs>
 102     </Member>
 103   </Members>
 104 </Type>