New article - resolving COM references (#13997)

ghogen · AaronRobinsonMSFT · denrea · web-flow · commit 79a7ff417fa8 · 2025-07-28T12:20:06.000-07:00
* Begin first draft of new article

* Rename

* some small improvements

* add more details

* add examples, other additions and edits

* more tweaks

* minor cleanup

* Apply suggestions from code review

Co-authored-by: Aaron Robinson &lt;arobins@microsoft.com&gt;

* Add toc, links, more text

* fix links

* Improvements general

* Add image and text

* more small changes

* more additions

* fix names of task and target

* Fix errors and improve tools section

* add file I/O section and other changes

* Mention failure to scan dependencies as another potential issue

* Change image to make it more readable

* Incorporate suggestions

* Acrolinx fixes

---------

Co-authored-by: Aaron Robinson &lt;arobins@microsoft.com&gt;
Co-authored-by: Dennis Rea &lt;v-denrea@microsoft.com&gt;
diff --git a/docs/msbuild/common-msbuild-project-items.md b/docs/msbuild/common-msbuild-project-items.md
@@ -53,6 +53,8 @@ This item doesn't apply to non-.NET projects.
 |WrapperTool|Optional string. The name of the wrapper tool that is used on the component. Values are:<br /><br />1. primary<br />2. tlbimp<br />3. primaryortlbimp<br />4. `aximp`|
 |Isolated|Optional boolean. Specifies whether the component is a reg-free component.|
 
+See [Troubleshoot COM references](troubleshoot-com-references.md).
+
 ## COMFileReference
 
 Represents a list of type libraries to reference by file path, instead of using the system registry. This type of reference can be a good alternative to COMReference in cases where you want to avoid a dependency on the build machine's registry, either because the account that runs the build doesn't have elevated privileges to edit the registry on the build server, or you don't want the build to have a dependency on the state of the registry. If you use `COMFileReference` to reference an artifact on a system path, then your build has a dependency on the system state. If the system artifact changes due to a change in the state of the system, such as when products are installed, updated, or uninstalled (or if you run the same build on a different machine), then the wrapper assembly can change, even if the build logic hasn't changed. To ensure a consistent build result, you can cache a known copy of the COM artifact in a place you control, such as under your project or solution folder, and reference that instead of the system artifact.
@@ -64,6 +66,8 @@ This item doesn't apply to non-.NET projects.
 |EmbedInteropTypes|Optional boolean. If true, embed the interop types from this reference directly into your assembly rather than generating an interop DLL.|
 |WrapperTool|Optional string. The name of the wrapper tool that is used on the component. Values are:<br /><br />1.  primary<br />2. tlbimp<br />3. primaryortlbimp<br />4. `aximp`|
 
+See [Troubleshoot COM references](troubleshoot-com-references.md).
+
 ## NativeReference
 
 Represents a native manifest file or a reference to such a file.
diff --git a/docs/msbuild/errors/msb3281.md b/docs/msbuild/errors/msb3281.md
@@ -21,7 +21,7 @@ ms.subservice: msbuild
 
 <!-- :::ErrorDefinitionDescription::: -->
 <!-- :::editable-content name="introDescription"::: -->
-This article describes the MSB3281 error code.
+This article describes the MSB3281 error code. 
 <!-- :::editable-content-end::: -->
 
 ## Message text
@@ -35,6 +35,9 @@ This article describes the MSB3281 error code.
 <!--
 {StrBegin="MSB3281: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3282.md b/docs/msbuild/errors/msb3282.md
@@ -35,6 +35,9 @@ This article describes the MSB3282 error code.
 <!--
 {StrBegin="MSB3282: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3283.md b/docs/msbuild/errors/msb3283.md
@@ -47,6 +47,10 @@ Check all the information provided in the `COMReference` or `COMFileReference`.
 `COMReference` uses the registry, so if you're using `COMReference`, you should verify that the COM component is correctly registered. See [Registering COM applications](/windows/win32/com/registering-com-applications).
 
 You can avoid registering the COM components on the build machine by using `COMFileReference`.
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3284.md b/docs/msbuild/errors/msb3284.md
@@ -40,6 +40,10 @@ This error occurs when MSBuild can't get the file path for a requested type libr
 Look to the additional information provided by the operating system to determine the cause of the problem. Typical causes include incorrect or invalid GUIDs, incorrect version numbers, or a component isn't installed.
 
 Try checking the registry yourself to make sure the requested component is represented. For more information, see [COM registry keys](/windows/win32/com/com-registry-keys).
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3285.md b/docs/msbuild/errors/msb3285.md
@@ -35,6 +35,10 @@ This article describes the MSB3285 error code.
 <!--
 {StrBegin="MSB3285: "}
 -->
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3286.md b/docs/msbuild/errors/msb3286.md
@@ -35,6 +35,10 @@ This article describes the MSB3286 error code.
 <!--
 {StrBegin="MSB3286: "}
 -->
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3287.md b/docs/msbuild/errors/msb3287.md
@@ -35,6 +35,9 @@ This article describes the MSB3287 error code.
 <!--
 {StrBegin="MSB3287: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3288.md b/docs/msbuild/errors/msb3288.md
@@ -35,6 +35,9 @@ This article describes the MSB3288 error code.
 <!--
 {StrBegin="MSB3288: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3290.md b/docs/msbuild/errors/msb3290.md
@@ -38,6 +38,10 @@ This error occurs when MSBuild tries to create the wrapper assembly for a type l
 ## Resolution
 
 The standard output message text is followed by additional information from the operating system. Look to the additional information provided to determine the cause of the problem.
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3291.md b/docs/msbuild/errors/msb3291.md
@@ -35,6 +35,9 @@ This article describes the MSB3291 error code.
 <!--
 {StrBegin="MSB3291: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3292.md b/docs/msbuild/errors/msb3292.md
@@ -35,6 +35,9 @@ This article describes the MSB3292 error code.
 <!--
 {StrBegin="MSB3292: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3293.md b/docs/msbuild/errors/msb3293.md
@@ -35,6 +35,9 @@ This article describes the MSB3293 error code.
 <!--
 {StrBegin="MSB3293: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3294.md b/docs/msbuild/errors/msb3294.md
@@ -35,6 +35,9 @@ This article describes the MSB3294 error code.
 <!--
 {StrBegin="MSB3294: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3295.md b/docs/msbuild/errors/msb3295.md
@@ -35,6 +35,9 @@ This article describes the MSB3295 error code.
 <!--
 {StrBegin="MSB3295: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3296.md b/docs/msbuild/errors/msb3296.md
@@ -35,6 +35,9 @@ This article describes the MSB3296 error code.
 <!--
 {StrBegin="MSB3296: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3297.md b/docs/msbuild/errors/msb3297.md
@@ -35,6 +35,9 @@ This article describes the MSB3297 error code.
 <!--
 {StrBegin="MSB3297: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3298.md b/docs/msbuild/errors/msb3298.md
@@ -35,6 +35,9 @@ This article describes the MSB3298 error code.
 <!--
 {StrBegin="MSB3298: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3299.md b/docs/msbuild/errors/msb3299.md
@@ -35,6 +35,9 @@ This article describes the MSB3299 error code.
 <!--
 {StrBegin="MSB3299: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3300.md b/docs/msbuild/errors/msb3300.md
@@ -35,6 +35,9 @@ This article describes the MSB3300 error code.
 <!--
 {StrBegin="MSB3300: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3302.md b/docs/msbuild/errors/msb3302.md
@@ -35,6 +35,9 @@ This article describes the MSB3302 error code.
 <!--
 {StrBegin="MSB3302: "}
 -->
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3303.md b/docs/msbuild/errors/msb3303.md
@@ -40,6 +40,10 @@ This error occurs when MSBuild fails to generate a .NET assembly (Primary Intero
 The standard output message text is followed by additional information from the operating system. Look to the additional information provided to determine the cause of the problem.
 
 If the subsequent error message is from the type library importer, you can also try running the *tlbimp.exe* importer directly to get a more detailed error message. For more information, see [TlbImp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) and [Add references to type libraries](/dotnet/framework/interop/how-to-add-references-to-type-libraries).
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3304.md b/docs/msbuild/errors/msb3304.md
@@ -40,6 +40,10 @@ This error is shown whenever there's an error that occurs when MSBuild scans a C
 Look to the extra error message to determine the cause of the problem.
 
 If the added error message is from the type library importer, you can also try running the *tlbimp.exe* importer directly to get a more detailed error message. For more information, see [TlbImp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) and [Add references to type libraries](/dotnet/framework/interop/how-to-add-references-to-type-libraries).
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3305.md b/docs/msbuild/errors/msb3305.md
@@ -53,6 +53,10 @@ As a temporary measure, you can silence the warning by adding the following valu
 > We don't recommend suppressing MSBuild diagnostic information. Eliminating the warning doesn't address the underlying problem. Using the ResolveComReferenceSilent property to hide the warning might also hide other COM reference warnings you don't intend to suppress.
 
 For more information, see [Add references to type libraries](/dotnet/framework/interop/how-to-add-references-to-type-libraries).
+
+## Related content
+
+- [Troubleshoot COM references](../troubleshoot-com-references.md).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/media/vs-2022/resolve-com-references-log-viewer.png b/docs/msbuild/media/vs-2022/resolve-com-references-log-viewer.png
diff --git a/docs/msbuild/resolvecomreference-task.md b/docs/msbuild/resolvecomreference-task.md
diff --git a/docs/msbuild/toc.yml b/docs/msbuild/toc.yml
diff --git a/docs/msbuild/troubleshoot-com-references.md b/docs/msbuild/troubleshoot-com-references.md
