Merge main to net8

.github/workflows/maestro-changelog.yml

@@ -0,0 +1,63 @@
+name: Add changelog for Maestro bump
+on: pull_request
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  add-changelog:
+    name: Add changelog
+    runs-on: ubuntu-latest
+    if: github.actor == 'dotnet-maestro[bot]'
+
+    steps:
+    - name: 'Compute changelog'
+      run: |
+        set -exo pipefail
+        git clone https://github.com/spouliot/dotnet-tools
+        cd dotnet-tools/changelog
+        dotnet run https://github.com/$GITHUB_REPOSITORY/pull/${GITHUB_REF_NAME/\/*/} > changelog.txt 2>&1
+
+        CHANGELOG_FILE=changelog2.txt
+        rm -f "$CHANGELOG_FILE"
+        cat changelog.txt | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g' >> "$CHANGELOG_FILE"
+        cat "$CHANGELOG_FILE"
+
+        cp "$CHANGELOG_FILE" /tmp/changelog.txt
+
+    - name: 'Add changelog'
+      uses: actions/[email protected]
+      with:
+        github-token: ${{secrets.GITHUB_TOKEN}}
+        script: |
+          const fs = require('fs');
+          const changelog_message = fs.readFileSync('/tmp/changelog.txt', 'utf8');
+          // check if we've already added a changelog to this PR, and if so, update that comment, otherwise add a new comment
+          var commentId = ""
+          await github.paginate (github.rest.issues.listComments,
+          {
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: context.issue.number
+          }).then ((comments) =>
+          {
+            const changelogComment = comments.find(comment => comment.body.includes (".net ChangeLog for") && comment.user.login == 'github-actions[bot]')
+            if (changelogComment)
+              commentId = changelogComment.id
+          })
+          if (commentId == "") {
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: changelog_message
+            })
+          } else {
+            github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: changelog_message
+            })
+          }

docs/design/APIChangeTracking.md

@@ -0,0 +1,151 @@
+# API Change Tracking
+
+.NET MAUI makes use of the `Microsoft.CodeAnalysis.PublicApiAnalyzers` NuGet to generate and track changes to public APIs to ensure that existing assemblies continue working without accidental breaking changes.
+
+To learn more about breaking change guidelines in .NET, including what is considered a "breaking change", check out these resources:
+
+* [.NET Runtime Breaking Change Rules](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-rules.md)
+* [.NET Runtime Breaking Change Definitions](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-change-definitions.md)
+* [.NET Library Guidance Breaking changes](https://learn.microsoft.com/dotnet/standard/library-guidance/breaking-changes)
+
+
+## Changing APIs
+
+In most cases, you are adding new APIs, so this is pretty simple and intellisense can be used. For changes and removes, these need to be properly tracked.
+
+### Adding New APIs
+
+If you are adding a new API, just go ahead and create the type/member and then use intellisense `ctrl + .` to fix the warning messages. You will have to do this for each TFM in the dropdown.
+
+If this does not work, you can do it manually by adding the fully qualified type/member name to the `PublicAPI.Unshipped.txt` file in each TFM where it is relevant.
+
+For example, we we are adding a new constructor to `PointerEventArgs`, we would add this line to unshipped file:
+
+```
+Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs(int clicks) -> void
+```
+
+### Changing / Removing APIs
+
+When an API is changed, the old API needs to be "removed" and then the new API can be added. Removing an API is as easy as copying the type/member from the `PublicAPI.Shipped.txt` file and added to the `PublicAPI.Unshipped.txt` with a prefixof `*REMOVED*`.
+
+For example, if we are removing a default constructor for some reason on the `PointerEventArgs` type:
+
+```
+Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs() -> void
+```
+
+All we would do is copy this line from the shipped file and add it to the unshipped file with the prefix:
+
+```
+*REMOVED*Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs() -> void
+```
+
+## Preparing API Releases
+
+Once everything is ready to be released and the branch is created, we can merge all the unshipped files into the shipped files. Then we can run a git diff on the files and see all the changes made between releases.
+
+### Merging the API Files
+
+To merge the API files, we just need to run a script - and then commit the changes to git:
+
+```
+.\eng\scripts\mark-shipped.ps1
+```
+
+Taking the examples above and assuming we had these files:
+
+`PublicAPI.Shipped.txt`:
+```
+#nullable enable
+Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs() -> void
+```
+
+`PublicAPI.Unshipped.txt`:
+```
+#nullable enable
+Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs(int clicks) -> void
+*REMOVED*Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs() -> void
+```
+
+After running the script, we will end up with this:
+
+`PublicAPI.Shipped.txt`:
+```
+#nullable enable
+Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs(int clicks) -> void
+```
+
+`PublicAPI.Unshipped.txt`:
+```
+#nullable enable
+```
+
+Note the "replaced" constructor after the API has been removed and the new one added.
+
+### Creating an API Diff
+
+Once we have committed the API files, we can use git to generate a diff:
+
+```
+git diff <previous-branch> <new-branch> --output=api-changes.diff **\PublicAPI.*.txt
+```
+
+And again the example above, we will have this result:
+
+```diff
+diff --git a/src/PublicAPI/net/PublicAPI.Shipped.txt b/src/Core/src/PublicAPI/net/PublicAPI.Shipped.txt
+index shashasha..shashasha
+--- a/src/Core/src/PublicAPI/net/PublicAPI.Shipped.txt
++++ b/src/Core/src/PublicAPI/net/PublicAPI.Shipped.txt
+@@ -1,2 +1,4 @@
+ #nullable enable
+-Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs() -> void
++Microsoft.Maui.Controls.PointerEventArgs.PointerEventArgs(int clicks) -> void
+```
+
+This diff can then be used to create a correct breaking API doc.
+
+## Enabling Tracking
+
+In order to enable tracking of a particular project, just add the following to the bottom of the .csproj:
+
+```xml
+<Import Project="$(MauiSrcDirectory)PublicAPI.targets" />
+```
+
+This will automatically start your project failing to build about missing things. This is just because the API tracker files are missing. We can use the `ctrl + .` or intellisense to automatically create them. Select each TFM from the dropdown in turn and pick any warning to use intellisense to generate the file for the entire project.
+
+For each TFM, there will be a set of files that are created in a `PublicAPI` folder:
+
+```
+PublicAPI
+ ├─ net
+ │   ├─ PublicAPI.Shipped.txt
+ │   └─ PublicAPI.Unshipped.txt
+ ├─ net-android
+ │   ├─ PublicAPI.Shipped.txt
+ │   └─ PublicAPI.Unshipped.txt
+ ├─ net-ios
+ │   ├─ PublicAPI.Shipped.txt
+ │   └─ PublicAPI.Unshipped.txt
+ ├─ net-maccatalyst
+ │   ├─ PublicAPI.Shipped.txt
+ │   └─ PublicAPI.Unshipped.txt
+ ├─ net-tizen
+ │   ├─ PublicAPI.Shipped.txt
+ │   └─ PublicAPI.Unshipped.txt
+ ├─ net-windows
+ │   ├─ PublicAPI.Shipped.txt
+ │   └─ PublicAPI.Unshipped.txt
+ └─ netstandard
+     ├─ PublicAPI.Shipped.txt
+     └─ PublicAPI.Unshipped.txt
+```
+
+If for some reason a file is not generated, they can be created manually with the contents of:
+
+```
+#nullable enable
+
+```

eng/PublicAPI.empty.txt

@@ -0,0 +1 @@
+#nullable enable

eng/Versions.props

@@ -39,11 +39,11 @@
     <MicrosoftAspNetCoreMetadataPackageVersion>7.0.0</MicrosoftAspNetCoreMetadataPackageVersion>
     <MicrosoftJSInteropPackageVersion>7.0.0</MicrosoftJSInteropPackageVersion>
     <!-- Other packages -->
-    <MicrosoftCodeAnalysisNetAnalyzersVersion>7.0.0-preview1.22559.1</MicrosoftCodeAnalysisNetAnalyzersVersion>
+    <MicrosoftCodeAnalysisNetAnalyzersVersion>7.0.0</MicrosoftCodeAnalysisNetAnalyzersVersion>
     <MicrosoftCodeAnalysisPublicApiAnalyzersVersion>3.3.3</MicrosoftCodeAnalysisPublicApiAnalyzersVersion>
     <MicrosoftCodeAnalysisBannedApiAnalyzersVersion>3.3.3</MicrosoftCodeAnalysisBannedApiAnalyzersVersion>
     <SystemNumericsVectorsVersion>4.5.0</SystemNumericsVectorsVersion>
-    <_MicrosoftWebWebView2Version>1.0.1418.22</_MicrosoftWebWebView2Version>
+    <_MicrosoftWebWebView2Version>1.0.1462.37</_MicrosoftWebWebView2Version>
     <!-- GLIDE - the android maven artifact in /src/Core/AndroidNative/maui/build.gradle -->
     <!-- must be kept in sync with the binding library version to it here: -->
     <_XamarinAndroidGlideVersion>4.13.2.2</_XamarinAndroidGlideVersion>

eng/automation/vs-workload.template.props

@@ -27,7 +27,7 @@
     <ComponentResources Include="maui-maccatalyst"  Version="@VS_COMPONENT_VERSION@" Category=".NET" Title=".NET MAUI SDK for Mac Catalyst" Description=".NET SDK Workload for building MAUI applications that target Mac Catalyst." />
     <ComponentResources Include="maui-ios"          Version="@VS_COMPONENT_VERSION@" Category=".NET" Title=".NET MAUI SDK for iOS" Description=".NET SDK Workload for building MAUI applications that target iOS." />
     <ComponentResources Include="maui-windows"      Version="@VS_COMPONENT_VERSION@" Category=".NET" Title=".NET MAUI SDK for Windows" Description=".NET SDK Workload for building MAUI applications that target Windows." />
-    <WorkloadPackages Include="$(NuGetPackagePath)\Microsoft.NET.Sdk.Maui.Manifest*.nupkg" Version="@VS_COMPONENT_VERSION@" />
+    <WorkloadPackages Include="$(NuGetPackagePath)\Microsoft.NET.Sdk.Maui.Manifest*.nupkg" Version="@VS_COMPONENT_VERSION@" SupportsMachineArch="true" />
     <MultiTargetPackNames Include="Maui.Sdk;Maui.Templates" />
   </ItemGroup>
 </Project>

eng/pipelines/common/pack.yml

@@ -1,16 +1,14 @@
 parameters:
   platform: ''
   poolName: ''
-  provisionatorChannel: latest
   artifact: 'nuget'
-
+  
 steps:
   - template: provision.yml
     parameters:
       platform: ${{ parameters.platform }}
       poolName: ${{ parameters.poolName }}
-      provisioning: true
-      provisionatorChannel: ${{ parameters.provisionatorChannel }}
+
   - pwsh: ./build.ps1 --target=dotnet --configuration="Release" --verbosity=diagnostic
     displayName: 'Install .NET'
     retryCountOnTaskFailure: 3

eng/pipelines/common/provision.yml

@@ -1,8 +1,14 @@
 parameters:
   platform : ''
-  skipXcode: false
   poolName: ''
+  skipXcode: false
+  skipVS: true
+  skipProvisioning: $(skipProvisionator)
+  provisionatorPath: $(provisionator.path)
+  provisionatorXCodePath: $(provisionator.xcode)
+  provisionatorVSPath: $(provisionator.vs)
   provisionatorChannel: 'latest'
+  provisionatorExtraArguments: $(provisionator.extraArguments)
 
 steps:
   # Prepare macOS
@@ -18,24 +24,23 @@ steps:
     - ${{ if ne(parameters.skipXcode, 'true') }}:
       - task: xamops.azdevex.provisionator-task.provisionator@2
         displayName: 'Provision Xcode'
-        condition: ne(variables['REQUIRED_XCODE'], '')
         inputs:
-          provisioning_script: $(provisionator.xcode)
-          provisioning_extra_args: $(provisionator.extraArguments)
+          provisioning_script: ${{ parameters.provisionatorXCodePath }}
+          provisioning_extra_args: ${{ parameters.provisionatorExtraArguments }}
         env:
           PROVISIONATOR_CHANNEL: ${{ parameters.provisionatorChannel }}
           AUTH_TOKEN_GITHUB_COM: $(github--pat--vs-mobiletools-engineering-service2)
     # Provision Additional Software
-    - task: xamops.azdevex.provisionator-task.provisionator@2
-      displayName: 'Provision Additional Software'
-      condition: eq(variables['provisioning'], 'true')
-      continueOnError: true 
-      inputs:
-        provisioning_script: $(provisionator.path)
-        provisioning_extra_args: $(provisionator.extraArguments)
-      env:
-        PROVISIONATOR_CHANNEL: ${{ parameters.provisionatorChannel }}
-        AUTH_TOKEN_GITHUB_COM: $(github--pat--vs-mobiletools-engineering-service2)
+    - ${{ if ne(parameters.skipProvisioning, 'true') }}:
+      - task: xamops.azdevex.provisionator-task.provisionator@2
+        displayName: 'Provision Additional Software'
+        continueOnError: true 
+        inputs:
+          provisioning_script: ${{ parameters.provisionatorPath }}
+          provisioning_extra_args: ${{ parameters.provisionatorExtraArguments }}
+        env:
+          PROVISIONATOR_CHANNEL: ${{ parameters.provisionatorChannel }}
+          AUTH_TOKEN_GITHUB_COM: $(github--pat--vs-mobiletools-engineering-service2)
 
     # Setup SDK Paths
     - bash: |
@@ -89,30 +94,30 @@ steps:
           msiexec.exe /package $output /quiet ADD_EXPLORER_CONTEXT_MENU_OPENPOWERSHELL=1 ENABLE_PSREMOTING=1 REGISTER_MANIFEST=1
         }
       displayName: 'Install PowerShell Core'
-    - task: xamops.azdevex.provisionator-task.provisionator@2
-      displayName: 'Provision Visual Studio'
-      condition: eq(variables['provisioningVS'], 'true')
-      inputs:
-        provisioning_script: $(provisionator.vs)
-      env:
-        PROVISIONATOR_CHANNEL: ${{ parameters.provisionatorChannel }}
-        AUTH_TOKEN_GITHUB_COM: $(github--pat--vs-mobiletools-engineering-service2)
-    - pwsh: |
-        $msbuild = "$env:ProgramFiles/Microsoft Visual Studio/2022/Preview/MSBuild/Current/Bin/MSBuild.exe"
-        echo "##vso[task.setvariable variable=MSBUILD_EXE]$msbuild"
-      displayName: 'Setup MSBuild Paths'
-      condition: eq(variables['provisioningVS'], 'true')
+    - ${{ if ne(parameters.skipVS, 'true') }}:
+      - task: xamops.azdevex.provisionator-task.provisionator@2
+        displayName: 'Provision Visual Studio'
+        condition: eq(variables['provisioningVS'], 'true')
+        inputs:
+          provisioning_script: ${{ parameters.provisionatorVSPath }}
+        env:
+          PROVISIONATOR_CHANNEL: ${{ parameters.provisionatorChannel }}
+          AUTH_TOKEN_GITHUB_COM: $(github--pat--vs-mobiletools-engineering-service2)
+      - pwsh: |
+          $msbuild = "$env:ProgramFiles/Microsoft Visual Studio/2022/Preview/MSBuild/Current/Bin/MSBuild.exe"
+          echo "##vso[task.setvariable variable=MSBUILD_EXE]$msbuild"
+        displayName: 'Setup MSBuild Paths'
 
     # Provision Additional Software
-    - task: xamops.azdevex.provisionator-task.provisionator@2
-      displayName: 'Provision Additional Software'
-      condition: eq('${{ parameters.provisioning }}', 'true')
-      inputs:
-        provisioning_script: $(provisionator.path)
-        provisioning_extra_args: $(provisionator.extraArguments)
-      env:
-        PROVISIONATOR_CHANNEL: ${{ parameters.provisionatorChannel }}
-        AUTH_TOKEN_GITHUB_COM: $(github--pat--vs-mobiletools-engineering-service2)
+    - ${{ if ne(parameters.skipProvisioning, 'true') }}:
+      - task: xamops.azdevex.provisionator-task.provisionator@2
+        displayName: 'Provision Additional Software'
+        inputs:
+          provisioning_script: ${{ parameters.provisionatorPath }}
+          provisioning_extra_args: ${{ parameters.provisionatorExtraArguments }}
+        env:
+          PROVISIONATOR_CHANNEL: ${{ parameters.provisionatorChannel }}
+          AUTH_TOKEN_GITHUB_COM: $(github--pat--vs-mobiletools-engineering-service2)
 
   # Prepare Both
   - task: UseDotNet@2                 # https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/tool/dotnet-core-tool-installer?view=azure-devops

eng/pipelines/common/variables.yml

@@ -37,6 +37,8 @@ variables:
   value: $(Build.ArtifactStagingDirectory)/logs
 - name: TestResultsDirectory
   value: $(Build.ArtifactStagingDirectory)/test-results
+- name: skipProvisionator
+  value: $[ne(variables['provisioning'], 'true')]
 - name: provisionator.xcode
   value: '$(System.DefaultWorkingDirectory)/eng/provisioning/xcode.csx'
 - name: provisionator.path