Skip to content

Commit 22a50ac

Browse files
jtschusterjtschuster
authored
[ComInterfaceGenerator] Recommend [In] and [Out] attributes on array parameters (#91094) (#91231)
Recommend that methods with array parameters use [In] or [Out] attributes if there are none already, and the parameter is not in, ref, or out.
1 parent 259a8a4 commit 22a50ac

36 files changed

+1160
-516
lines changed

‎docs/project/list-of-diagnostics.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ The diagnostic id values reserved for .NET Libraries analyzer warnings are `SYSL
208208
| __`SYSLIB1089`__ | _`SYSLIB1070`-`SYSLIB1089` reserved for System.Runtime.InteropServices.JavaScript.JSImportGenerator._ |
209209
| __`SYSLIB1090`__ | Invalid 'GeneratedComInterfaceAttribute' usage |
210210
| __`SYSLIB1091`__ | Method is declared in different partial declaration than the 'GeneratedComInterface' attribute. |
211-
| __`SYSLIB1092`__ | 'GenerateComInterfaceAttribute' usage not recommended. See aka.ms/GeneratedComInterfaceUsage for recommended usage. |
211+
| __`SYSLIB1092`__ | Usage of '[LibraryImport|GeneratedComInterface]' does not follow recommendation. See aka.ms/[LibraryImport|GeneratedComInterface]Usage for best practices. |
212212
| __`SYSLIB1093`__ | Analysis for COM interface generation has failed |
213213
| __`SYSLIB1094`__ | The base COM interface failed to generate source. Code will not be generated for this interface. |
214214
| __`SYSLIB1095`__ | Invalid 'GeneratedComClassAttribute' usage |

‎src/libraries/System.Runtime.InteropServices/gen/ComInterfaceGenerator/DiagnosticDescriptorProvider.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ internal sealed class DiagnosticDescriptorProvider : IDiagnosticDescriptorProvid
2626
GeneratorDiagnostic.NotSupported { NotSupportedDetails: not null, TypePositionInfo.IsManagedReturnPosition: false } => GeneratorDiagnostics.ParameterTypeNotSupportedWithDetails,
2727
GeneratorDiagnostic.UnnecessaryData { TypePositionInfo.IsManagedReturnPosition: false } => GeneratorDiagnostics.UnnecessaryParameterMarshallingInfo,
2828
GeneratorDiagnostic.UnnecessaryData { TypePositionInfo.IsManagedReturnPosition: true } => GeneratorDiagnostics.UnnecessaryReturnMarshallingInfo,
29+
GeneratorDiagnostic.NotRecommended => GeneratorDiagnostics.GeneratedComInterfaceUsageDoesNotFollowBestPractices,
2930
{ IsFatal: false } => null,
3031
{ TypePositionInfo.IsManagedReturnPosition: true } => GeneratorDiagnostics.ReturnTypeNotSupported,
3132
{ TypePositionInfo.IsManagedReturnPosition: false } => GeneratorDiagnostics.ParameterTypeNotSupported,

‎src/libraries/System.Runtime.InteropServices/gen/ComInterfaceGenerator/GeneratorDiagnostics.cs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -485,6 +485,17 @@ public class Ids
485485
DiagnosticSeverity.Info,
486486
isEnabledByDefault: true);
487487

488+
/// <inheritdoc cref="SR.ComInterfaceUsageDoesNotFollowBestPracticesMessageWithDetails"/>
489+
public static readonly DiagnosticDescriptor GeneratedComInterfaceUsageDoesNotFollowBestPractices =
490+
new DiagnosticDescriptor(
491+
Ids.NotRecommendedGeneratedComInterfaceUsage,
492+
GetResourceString(nameof(SR.ComInterfaceUsageDoesNotFollowBestPracticesTitle)),
493+
GetResourceString(nameof(SR.ComInterfaceUsageDoesNotFollowBestPracticesMessageWithDetails)),
494+
Category,
495+
DiagnosticSeverity.Info,
496+
isEnabledByDefault: true,
497+
helpLinkUri: "aka.ms/GeneratedComInterfaceUsage");
498+
488499
/// <summary>
489500
/// Report diagnostic for invalid configuration for string marshalling.
490501
/// </summary>

‎src/libraries/System.Runtime.InteropServices/gen/Common/Resources/Strings.resx‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -875,7 +875,13 @@
875875
<value>[In] and [Out] attributes</value>
876876
</data>
877877
<data name="OutAttributeNotSupportedOnByValueParameters" xml:space="preserve">
878-
<value>The `[Out]` attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</value>
878+
<value>The '[Out]' attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</value>
879+
</data>
880+
<data name="InAttributeNotSupportedOnByValueParameters" xml:space="preserve">
881+
<value>The '[In]' attribute is only supported on array parameters. By-value parameters are considered read-only by default.</value>
882+
</data>
883+
<data name="InOutAttributeNotSupportedOnByValueParameters" xml:space="preserve">
884+
<value>The '[In]' and '[Out]' attributes are only supported on array parameters. Consider using the 'ref' keyword to make the parameter mutable.</value>
879885
</data>
880886
<data name="ComMethodReturningIntWillBeOutParameterMessage" xml:space="preserve">
881887
<value>The return value in the managed definition will be converted to an 'out' parameter when calling the unmanaged COM method. If the return value is intended to be the HRESULT code returned by the unmanaged COM method, use '[PreserveSig]' on the method.</value>
@@ -889,4 +895,19 @@
889895
<data name="HResultTypeWillBeTreatedAsStructTitle" xml:space="preserve">
890896
<value>This type will be treated as a struct in the native signature, not as a native HRESULT</value>
891897
</data>
892-
</root>
898+
<data name="PreferExplicitInOutAttributesOnArrays" xml:space="preserve">
899+
<value>It is recommended to use explicit '[In]' and '[Out]' attributes on array parameters.</value>
900+
</data>
901+
<data name="ComInterfaceUsageDoesNotFollowBestPracticesTitle" xml:space="preserve">
902+
<value>The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations.</value>
903+
</data>
904+
<data name="ComInterfaceUsageDoesNotFollowBestPracticesMessageWithDetails" xml:space="preserve">
905+
<value>The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations. {0}</value>
906+
</data>
907+
<data name="LibraryImportUsageDoesNotFollowBestPracticesTitle" xml:space="preserve">
908+
<value>The usage of 'LibraryImportAttribute' does not follow recommendations.</value>
909+
</data>
910+
<data name="LibraryImportUsageDoesNotFollowBestPracticesMessageWithDetails" xml:space="preserve">
911+
<value>The usage of 'LibraryImportAttribute' does not follow recommendations. {0}</value>
912+
</data>
913+
</root>

‎src/libraries/System.Runtime.InteropServices/gen/Common/Resources/xlf/Strings.cs.xlf‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,16 @@
147147
<target state="translated">Hostování .NET COM s EnableComHosting nepodporuje rozhraní s generatedComInterfaceAttribute</target>
148148
<note />
149149
</trans-unit>
150+
<trans-unit id="ComInterfaceUsageDoesNotFollowBestPracticesMessageWithDetails">
151+
<source>The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations. {0}</source>
152+
<target state="new">The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations. {0}</target>
153+
<note />
154+
</trans-unit>
155+
<trans-unit id="ComInterfaceUsageDoesNotFollowBestPracticesTitle">
156+
<source>The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations.</source>
157+
<target state="new">The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations.</target>
158+
<note />
159+
</trans-unit>
150160
<trans-unit id="ComMethodReturningIntWillBeOutParameterMessage">
151161
<source>The return value in the managed definition will be converted to an 'out' parameter when calling the unmanaged COM method. If the return value is intended to be the HRESULT code returned by the unmanaged COM method, use '[PreserveSig]' on the method.</source>
152162
<target state="translated">Vrácená hodnota ve spravované definici se při volání nespravované metody COM převede na parametr out. Pokud má být návratovou hodnotou kód HRESULT vrácený nespravovanou metodou COM, použijte u metody [PreserveSig].</target>
@@ -447,6 +457,11 @@
447457
<target state="translated">Tento typ bude v nativním podpisu považován za strukturu, nikoli za nativní HRESULT.</target>
448458
<note />
449459
</trans-unit>
460+
<trans-unit id="InAttributeNotSupportedOnByValueParameters">
461+
<source>The '[In]' attribute is only supported on array parameters. By-value parameters are considered read-only by default.</source>
462+
<target state="new">The '[In]' attribute is only supported on array parameters. By-value parameters are considered read-only by default.</target>
463+
<note />
464+
</trans-unit>
450465
<trans-unit id="InAttributeNotSupportedWithoutOutBlittableArray">
451466
<source>The '[In]' attribute is not supported unless the '[Out]' attribute is also used. Blittable arrays cannot be marshalled as '[In]' only.</source>
452467
<target state="translated">Atribut [In] není podporován, pokud není použit také atribut [Out]. Blittable arrays nelze zařadit pouze jako [In].</target>
@@ -467,6 +482,11 @@
467482
<target state="translated">Poskytnuté atributy „[In]“ a „[Out]“ u tohoto parametru se na tomto parametru nepodporují.</target>
468483
<note />
469484
</trans-unit>
485+
<trans-unit id="InOutAttributeNotSupportedOnByValueParameters">
486+
<source>The '[In]' and '[Out]' attributes are only supported on array parameters. Consider using the 'ref' keyword to make the parameter mutable.</source>
487+
<target state="new">The '[In]' and '[Out]' attributes are only supported on array parameters. Consider using the 'ref' keyword to make the parameter mutable.</target>
488+
<note />
489+
</trans-unit>
470490
<trans-unit id="InOutAttributes">
471491
<source>[In] and [Out] attributes</source>
472492
<target state="translated">atributy [In] a [Out]</target>
@@ -702,6 +722,16 @@
702722
<target state="translated">Neplatné použití atributu VirtualMethodIndexAttribute</target>
703723
<note />
704724
</trans-unit>
725+
<trans-unit id="LibraryImportUsageDoesNotFollowBestPracticesMessageWithDetails">
726+
<source>The usage of 'LibraryImportAttribute' does not follow recommendations. {0}</source>
727+
<target state="new">The usage of 'LibraryImportAttribute' does not follow recommendations. {0}</target>
728+
<note />
729+
</trans-unit>
730+
<trans-unit id="LibraryImportUsageDoesNotFollowBestPracticesTitle">
731+
<source>The usage of 'LibraryImportAttribute' does not follow recommendations.</source>
732+
<target state="new">The usage of 'LibraryImportAttribute' does not follow recommendations.</target>
733+
<note />
734+
</trans-unit>
705735
<trans-unit id="LinearCollectionElementTypesMustMatchDescription">
706736
<source>The element type of the 'ReadOnlySpan' returned by 'GetManagedValuesSource' must be the same as the element type returned by 'GetManagedValuesDestination'.</source>
707737
<target state="translated">Typ prvku ReadOnlySpan vrácený GetManagedValuesSource musí být stejný, jako typ prvku vrácený GetManagedValuesDestination.</target>
@@ -903,8 +933,8 @@
903933
<note />
904934
</trans-unit>
905935
<trans-unit id="OutAttributeNotSupportedOnByValueParameters">
906-
<source>The `[Out]` attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</source>
907-
<target state="translated">Atribut „[Out]“ se podporuje pouze u parametrů pole. Zvažte použití klíčových slov „out“ nebo „ref“, aby se parametr dalo měnit.</target>
936+
<source>The '[Out]' attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</source>
937+
<target state="new">The '[Out]' attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</target>
908938
<note />
909939
</trans-unit>
910940
<trans-unit id="OutRequiresToManagedDescription">
@@ -917,6 +947,11 @@
917947
<target state="translated">Typ {0}určuje, že podporuje zařazování ve směru „Out“, ale neposkytuje metodu ToManaged, která vrací spravovaný typ</target>
918948
<note />
919949
</trans-unit>
950+
<trans-unit id="PreferExplicitInOutAttributesOnArrays">
951+
<source>It is recommended to use explicit '[In]' and '[Out]' attributes on array parameters.</source>
952+
<target state="new">It is recommended to use explicit '[In]' and '[Out]' attributes on array parameters.</target>
953+
<note />
954+
</trans-unit>
920955
<trans-unit id="RequiresAllowUnsafeBlocksDescriptionCom">
921956
<source>'GeneratedComInterfaceAttribute' and 'GeneratedComClassAttribute' require unsafe code. Project must be updated with '&lt;AllowUnsafeBlocks&gt;true&lt;/AllowUnsafeBlocks&gt;'.</source>
922957
<target state="translated">GeneratedComInterfaceAttribute a GeneratedComClassAttribute vyžadují nebezpečný kód. Projekt se musí aktualizovat na &lt;AllowUnsafeBlocks&gt;true&lt;/AllowUnsafeBlocks&gt;.</target>
@@ -1276,4 +1311,4 @@
12761311
</trans-unit>
12771312
</body>
12781313
</file>
1279-
</xliff>
1314+
</xliff>

‎src/libraries/System.Runtime.InteropServices/gen/Common/Resources/xlf/Strings.de.xlf‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,16 @@
147147
<target state="translated">Das .NET COM-Hosting mit "EnableComHosting" unterstützt keine Schnittstellen mit "GeneratedComInterfaceAttribute".</target>
148148
<note />
149149
</trans-unit>
150+
<trans-unit id="ComInterfaceUsageDoesNotFollowBestPracticesMessageWithDetails">
151+
<source>The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations. {0}</source>
152+
<target state="new">The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations. {0}</target>
153+
<note />
154+
</trans-unit>
155+
<trans-unit id="ComInterfaceUsageDoesNotFollowBestPracticesTitle">
156+
<source>The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations.</source>
157+
<target state="new">The usage of 'GeneratedComInterfaceAttribute' does not follow recommendations.</target>
158+
<note />
159+
</trans-unit>
150160
<trans-unit id="ComMethodReturningIntWillBeOutParameterMessage">
151161
<source>The return value in the managed definition will be converted to an 'out' parameter when calling the unmanaged COM method. If the return value is intended to be the HRESULT code returned by the unmanaged COM method, use '[PreserveSig]' on the method.</source>
152162
<target state="translated">Der Rückgabewert in der verwalteten Definition wird beim Aufrufen der nicht verwalteten COM-Methode in einen out-Parameter konvertiert. Wenn als Rückgabewert der von der nicht verwalteten COM-Methode zurückgegebene HRESULT-Code eingesetzt werden soll, verwenden Sie "[PreserveSig]" für die Methode.</target>
@@ -447,6 +457,11 @@
447457
<target state="translated">Dieser Typ wird als Struktur in der nativen Signatur und nicht als natives HRESULT behandelt</target>
448458
<note />
449459
</trans-unit>
460+
<trans-unit id="InAttributeNotSupportedOnByValueParameters">
461+
<source>The '[In]' attribute is only supported on array parameters. By-value parameters are considered read-only by default.</source>
462+
<target state="new">The '[In]' attribute is only supported on array parameters. By-value parameters are considered read-only by default.</target>
463+
<note />
464+
</trans-unit>
450465
<trans-unit id="InAttributeNotSupportedWithoutOutBlittableArray">
451466
<source>The '[In]' attribute is not supported unless the '[Out]' attribute is also used. Blittable arrays cannot be marshalled as '[In]' only.</source>
452467
<target state="translated">Das [In]-Attribut wird nur unterstützt, wenn auch das [Out]-Attribut verwendet wird. Blittable-Arrays können nicht nur als "[In]" gemarshallt werden.</target>
@@ -467,6 +482,11 @@
467482
<target state="translated">Die angegebenen Attribute \"[In]\" und \"[Out]\" für diesen Parameter werden für diesen Parameter nicht unterstützt.</target>
468483
<note />
469484
</trans-unit>
485+
<trans-unit id="InOutAttributeNotSupportedOnByValueParameters">
486+
<source>The '[In]' and '[Out]' attributes are only supported on array parameters. Consider using the 'ref' keyword to make the parameter mutable.</source>
487+
<target state="new">The '[In]' and '[Out]' attributes are only supported on array parameters. Consider using the 'ref' keyword to make the parameter mutable.</target>
488+
<note />
489+
</trans-unit>
470490
<trans-unit id="InOutAttributes">
471491
<source>[In] and [Out] attributes</source>
472492
<target state="translated">[In]- und [Out]-Attribute</target>
@@ -702,6 +722,16 @@
702722
<target state="translated">Ungültige Verwendung von "VirtualMethodIndexAttribute"</target>
703723
<note />
704724
</trans-unit>
725+
<trans-unit id="LibraryImportUsageDoesNotFollowBestPracticesMessageWithDetails">
726+
<source>The usage of 'LibraryImportAttribute' does not follow recommendations. {0}</source>
727+
<target state="new">The usage of 'LibraryImportAttribute' does not follow recommendations. {0}</target>
728+
<note />
729+
</trans-unit>
730+
<trans-unit id="LibraryImportUsageDoesNotFollowBestPracticesTitle">
731+
<source>The usage of 'LibraryImportAttribute' does not follow recommendations.</source>
732+
<target state="new">The usage of 'LibraryImportAttribute' does not follow recommendations.</target>
733+
<note />
734+
</trans-unit>
705735
<trans-unit id="LinearCollectionElementTypesMustMatchDescription">
706736
<source>The element type of the 'ReadOnlySpan' returned by 'GetManagedValuesSource' must be the same as the element type returned by 'GetManagedValuesDestination'.</source>
707737
<target state="translated">Der von \"GetManagedValuesSource\" zurückgegebene Elementtyp \"ReadOnlySpan\" muss mit dem Elementtyp identisch sein, der von \"GetManagedValuesDestination\" zurückgegeben wird.</target>
@@ -903,8 +933,8 @@
903933
<note />
904934
</trans-unit>
905935
<trans-unit id="OutAttributeNotSupportedOnByValueParameters">
906-
<source>The `[Out]` attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</source>
907-
<target state="translated">Das [Out]-Attribut wird nur für Arrayparameter gemarshallt werden. Erwägen Sie die Verwendung der Schlüsselwörter "out" oder "ref", um den Parameter änderbar zu machen.</target>
936+
<source>The '[Out]' attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</source>
937+
<target state="new">The '[Out]' attribute is only supported on array parameters. Consider using 'out' or 'ref' keywords to make the parameter mutable.</target>
908938
<note />
909939
</trans-unit>
910940
<trans-unit id="OutRequiresToManagedDescription">
@@ -917,6 +947,11 @@
917947
<target state="translated">Der Typ \"{0}\" gibt an, dass das Marshalling in der Out-Richtung unterstützt wird. Er stellt jedoch keine ToManaged-Methode bereit, die den verwalteten Typ zurückgibt.</target>
918948
<note />
919949
</trans-unit>
950+
<trans-unit id="PreferExplicitInOutAttributesOnArrays">
951+
<source>It is recommended to use explicit '[In]' and '[Out]' attributes on array parameters.</source>
952+
<target state="new">It is recommended to use explicit '[In]' and '[Out]' attributes on array parameters.</target>
953+
<note />
954+
</trans-unit>
920955
<trans-unit id="RequiresAllowUnsafeBlocksDescriptionCom">
921956
<source>'GeneratedComInterfaceAttribute' and 'GeneratedComClassAttribute' require unsafe code. Project must be updated with '&lt;AllowUnsafeBlocks&gt;true&lt;/AllowUnsafeBlocks&gt;'.</source>
922957
<target state="translated">'GeneratedComInterfaceAttribute' und 'GeneratedComClassAttribute' erfordern unsicheren Code. Das Projekt muss mit '&lt;AllowUnsafeBlocks&gt;wahr&lt;/AllowUnsafeBlocks&gt;' aktualisiert werden.</target>
@@ -1276,4 +1311,4 @@
12761311
</trans-unit>
12771312
</body>
12781313
</file>
1279-
</xliff>
1314+
</xliff>

0 commit comments

Comments
 (0)