Windows SDK projection release notes (#9526)

* Add Windows SDK projection release notes

* Update wording

* Update release notes wording

* Improve wording

release-notes/8.0/known-issues.md

@@ -34,3 +34,30 @@ macOS 15 uses a different status code to indicate a key is not in a Keychain tha
 If you have not already upgraded to macOS 15 from a prior version and use .NET, you are not impacted by this issue.  If you are planning to upgrade to macOS 15, the workaround is to upgrade to .NET 8.0.10 (scheduled for October 2024) prior to upgrading to macOS 15.
 
 Loading a certificate and its associated private key from a PKCS#12/PFX are not affected.  If you are using an application that supports loading a certificate (and associated private key) by either PFX or PEM, converting your PEM contents to PFX - and updating configuration appropriately - may unblock you.
+
+## Windows SDK projections
+
+If you target the Windows 10 OS version target framework (i.e. `net8.0-windows10.0.22000.0`) and run into one of the below compiler errors, **see the [CsWinRT issue](https://github.com/microsoft/CsWinRT/issues/1809) for how to get the fix**. The fix will be available by default in an upcoming .NET SDK update.
+
+### 1. Partial type nested within a non-partial type
+
+If you have a type marked `partial` implementing WinRT mapped interfaces nested within a type that isn't marked `partial`, you may see the below compiler error instead of a diagnostic message with a code fix indicating that the outer type needs to be made `partial`.
+
+```
+CS0260 Missing partial modifier on declaration of type '..'; another partial declaration of this type exists
+```
+
+### 2. Special characters in assembly name (dashes)
+
+If you have certain special characters in your assembly name (i.e. `-`) and you have WinRT generic instantiation scenarios, you may notice the generated code doesn't compile due to the source generator fails to escape all possible special characters not allowed in identifiers.
+
+```
+WinRT.SourceGenerator\Generator.WinRTAotSourceGenerator\WinRTGenericInstantiation.g.cs
+WinRT.SourceGenerator\Generator.WinRTAotSourceGenerator\WinRTGlobalVtableLookup.g.cs
+
+error CS0116: A namespace cannot directly contain members such as fields, methods or statements
+error CS1514: { expected
+error CS1022: Type or namespace definition, or end-of-file expected
+error CS0118: 'WinRT.Text' is a namespace but is used like a variable
+error CS0103: The name 'GenericHelpers' does not exist in the current context
+```

release-notes/9.0/known-issues.md

@@ -82,3 +82,46 @@ macOS 15 uses a different status code to indicate a key is not in a Keychain tha
 If you have not already upgraded to macOS 15 from a prior version and use .NET, you are not impacted by this issue.  If you are planning to upgrade to macOS 15, the workaround is to upgrade to .NET 9.0.0-rc2 (scheduled for October 2024) prior to upgrading to macOS 15.
 
 Loading a certificate and its associated private key from a PKCS#12/PFX are not affected.  If you are using an application that supports loading a certificate (and associated private key) by either PFX or PEM, converting your PEM contents to PFX - and updating configuration appropriately - may unblock you.
+
+## Windows SDK projections
+
+If you target the Windows 10 OS version target framework (i.e. `net8.0-windows10.0.22000.0`) and run into one of the below compiler errors, **see the [CsWinRT issue](https://github.com/microsoft/CsWinRT/issues/1809) for how to get the fix**. The fix will be available by default in an upcoming .NET SDK update.
+
+### 1. Partial type nested within a non-partial type
+
+If you have a type marked `partial` implementing WinRT mapped interfaces nested within a type that isn't marked `partial`, you may see the below compiler error instead of a diagnostic message with a code fix indicating that the outer type needs to be made `partial`.
+
+```
+CS0260 Missing partial modifier on declaration of type '..'; another partial declaration of this type exists
+```
+
+### 2. Special characters in assembly name (dashes)
+
+If you have certain special characters in your assembly name (i.e. `-`) and you have WinRT generic instantiation scenarios, you may notice the generated code doesn't compile due to the source generator fails to escape all possible special characters not allowed in identifiers.
+
+```
+WinRT.SourceGenerator\Generator.WinRTAotSourceGenerator\WinRTGenericInstantiation.g.cs
+WinRT.SourceGenerator\Generator.WinRTAotSourceGenerator\WinRTGlobalVtableLookup.g.cs
+
+error CS0116: A namespace cannot directly contain members such as fields, methods or statements
+error CS1514: { expected
+error CS1022: Type or namespace definition, or end-of-file expected
+error CS0118: 'WinRT.Text' is a namespace but is used like a variable
+error CS0103: The name 'GenericHelpers' does not exist in the current context
+```
+
+### 3. Using WindowsSdkPackageVersion with older package versions
+
+The .NET 9 SDK now supports profiles for the Windows SDK projection package. Due to that, if you use `WindowsSdkPackageVersion` to explicitly specify an older version of the package without profiles (i.e. before the `.38` version), you will see no types from `Microsoft.Windows.SDK.NET.dll` resolve.
+
+### Mitigation
+
+If you had previously specified the `WindowsSdkPackageVersion` property to get a version of the package not available in the .NET SDK, you can remove that property as the .NET SDK now has a newer version of the package including for `26100`.
+
+If you had previously specified the `WindowsSdkPackageVersion` property to fix the version of the package to control your dependencies and need to stay on the older version, you can add the below to your `csproj` or a common `props` or `targets` file to workaround the issue. This will be done automatically by the .NET 9 SDK in an upcoming update upon which you can remove it.
+
+```
+<ItemGroup Condition=" '$(IncludeWindowsSDKRefFrameworkReferences)' == 'true' ">
+    <FrameworkReference Include="Microsoft.Windows.SDK.NET.Ref" IsImplicitlyDefined="true" Pack="false" PrivateAssets="All" />
+</ItemGroup> 
+```