Add GAC info to docs (#1986)

CHANGELOG.md

@@ -57,6 +57,8 @@ This beta release is built on top of [OpenTelemetry .NET](https://github.com/ope
  can be enabled or disabled via the
  `OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED` environment variable.
  See the [additional settings](./docs/config.md#additional-settings) table for details.
+- Add automatic Global Assembly Cache (GAC) registration, of the distributed
+ .NET Framework assemblies, to the PowerShell installation module.
 
 ### Changed
 

docs/design.md

@@ -221,6 +221,9 @@ Two issues might arise from incorrect versioning:
 2. Multiple versions of the assembly in the same process,
    as the runtime treats them independently.
 
+On the .NET Framework, by default, the CLR Profiler redirects any
+assembly references to the versions shipped with the Managed Profiler.
+
 #### Configuration resolution
 
 .NET [Framework-dependent deployment](https://docs.microsoft.com/en-us/dotnet/core/deploying/deploy-with-cli#framework-dependent-deployment)

docs/troubleshooting.md

@@ -20,24 +20,28 @@ To handle dependency versions conflicts,
 update the instrumented application's project references
 to use the same versions.
 
-When a rebuild is not possible,
+For .NET Framework applications the assembly references are, by default, updated
-for .NET Framework applications the workaround is to use binding redirects.
+during runtime to the versions used by the automatic instrumentation.
-You can redirect a range of assembly versions to a specific version
+This behavior can be controlled via the [`OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED`](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/config.md#additional-settings)
-that is not available at build time.
+setting.
 
-## No proper relationship between spans
+For the automatic redirection above to work there are two specific scenarios that
+require the assemblies used to instrument .NET Framework
+applications, the ones under the `netfx` folder of the installation directory,
+to be also installed into the Global Assembly Cache (GAC):
 
-On .NET Framework, strong name signing can force the loading of multiple versions
+1. [__Monkey patch instrumentation__](https://en.wikipedia.org/wiki/Monkey_patch#:~:text=Monkey%20patching%20is%20a%20technique,Python%2C%20Groovy%2C%20etc.)
-of the same assembly on the same process. This causes a separate hierarchy of
+of assemblies loaded as domain-neutral.
-Activity objects. If you are referencing packages in your application that use a
+2. Assembly redirection for strong-named applications if the app also ships
-version of the `System.Diagnostics.DiagnosticSource` different than the `OpenTelemetry.Api`
+different versions of some assemblies also shipped in the `netfx` folder.
-version used by the OpenTelemetry .NET Automatic Instrumentation, reference
-the correct version of the `System.Diagnostics.DiagnosticSource` package
-in your application.
-This causes automatic binding redirection to solve the issue.
 
-If automatic binding redirection is [disabled](https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/how-to-enable-and-disable-automatic-binding-redirection)
+If you are having problems in one of the scenarios above run again the
-you can also manually add binding redirection to the `App.config` file.
+`Install-OpenTelemetryCore` command from the
+[PowerShell installation module](../OpenTelemetry.DotNet.Auto.psm1)
+to ensure that the required GAC installations are updated.
+
+For more information about the GAC usage by the automatic instrumentation,
+see [here](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/issues/1906#issuecomment-1376292814).
 
 ## High CPU usage