|
| 1 | +# Component Governance Manifest (cgmanifest.json) |
| 2 | + |
| 3 | +This document explains how to manage, update, and include the `cgmanifest.json` file in the MAUI project. |
| 4 | + |
| 5 | +## What is cgmanifest.json? |
| 6 | + |
| 7 | +The Component Governance Manifest (`cgmanifest.json`) is a file that lists all the third-party components used in the project. It helps with tracking dependencies and their versions for security and compliance purposes. |
| 8 | + |
| 9 | +## Automatic Generation |
| 10 | + |
| 11 | +The project includes scripts to automatically generate and update the `cgmanifest.json` file with package versions from the `Versions.props` file. |
| 12 | + |
| 13 | +### Using Cake Build Script |
| 14 | + |
| 15 | +Run the `GenerateCgManifest` task: |
| 16 | + |
| 17 | +```bash |
| 18 | +dotnet tool resotre |
| 19 | +dotnet cake --target=GenerateCgManifest --workloads=global |
| 20 | +``` |
| 21 | + |
| 22 | +### Using Scripts Directly |
| 23 | + |
| 24 | +You can also run the PowerShell script directly (works on both Windows and macOS/Linux): |
| 25 | + |
| 26 | +```bash |
| 27 | +# On all platforms (Windows/macOS/Linux) |
| 28 | +pwsh -ExecutionPolicy Bypass -File ./eng/scripts/update-cgmanifest.ps1 |
| 29 | +``` |
| 30 | + |
| 31 | +### MSBuild Integration |
| 32 | + |
| 33 | +The `CgManifest.targets` file provides MSBuild integration. |
| 34 | + |
| 35 | +#### Default Behavior |
| 36 | + |
| 37 | +By default, the cgmanifest.json file is **always generated** during build, but it is **not included** in the NuGet package. This ensures the manifest is always up-to-date without affecting package contents. |
| 38 | + |
| 39 | +#### Manual Generation |
| 40 | + |
| 41 | +You can explicitly generate the manifest file: |
| 42 | + |
| 43 | +```bash |
| 44 | +dotnet build -t:GenerateCgManifest |
| 45 | +``` |
| 46 | + |
| 47 | +#### Disabling Generation |
| 48 | + |
| 49 | +If needed, you can temporarily disable the automatic generation: |
| 50 | + |
| 51 | +```bash |
| 52 | +dotnet build -p:UpdateCgManifestBeforeBuild=false |
| 53 | +``` |
| 54 | + |
| 55 | +## Including CG Manifest in CI Builds |
| 56 | + |
| 57 | +For CI builds where you want to include the cgmanifest.json in the package: |
| 58 | + |
| 59 | +```bash |
| 60 | +dotnet build -p:GenerateCgManifest=true |
| 61 | +``` |
| 62 | +OR |
| 63 | +```bash |
| 64 | +dotnet pack -p:GenerateCgManifest=true |
| 65 | +``` |
| 66 | + |
| 67 | +This will: |
| 68 | +1. Generate the cgmanifest.json file (happens by default) |
| 69 | +2. Include it in the package (for Template projects) |
| 70 | + |
| 71 | +### Azure DevOps Pipeline |
| 72 | + |
| 73 | +Add the following step to your YAML pipeline to include the cgmanifest.json file in the package: |
| 74 | + |
| 75 | +```yaml |
| 76 | +- task: DotNetCoreCLI@2 |
| 77 | + displayName: 'Pack with CG Manifest' |
| 78 | + inputs: |
| 79 | + command: 'pack' |
| 80 | + packagesToPack: 'src/Templates/src/Microsoft.Maui.Templates.csproj' |
| 81 | + packDirectory: '$(Build.ArtifactStagingDirectory)/nuget' |
| 82 | + arguments: '-p:GenerateCgManifest=true' |
| 83 | +``` |
| 84 | +
|
| 85 | +### GitHub Actions |
| 86 | +
|
| 87 | +For GitHub Actions workflows, add this step: |
| 88 | +
|
| 89 | +```yaml |
| 90 | +- name: Pack with CG Manifest |
| 91 | + run: dotnet pack src/Templates/src/Microsoft.Maui.Templates.csproj -p:GenerateCgManifest=true -o $GITHUB_WORKSPACE/artifacts/nuget |
| 92 | +``` |
| 93 | +
|
| 94 | +## Customizing Package Mappings |
| 95 | +
|
| 96 | +To add or modify package mappings, edit the PowerShell script: `eng/scripts/update-cgmanifest.ps1` (look for `$packageVersionMappings` hashtable). |
| 97 | + |
| 98 | +## Special Handling for Multiple Versions |
| 99 | + |
| 100 | +The script has special handling for packages that need multiple versions to be included in the manifest: |
| 101 | + |
| 102 | +- **CommunityToolkit.Maui**: Both the current version (`CommunityToolkitMauiPackageVersion`) and previous version (`CommunityToolkitMauiPreviousPackageVersion`) from `Versions.props` are included. |
| 103 | + |
| 104 | +To add similar handling for other packages, modify the script to add special case handling like that implemented for CommunityToolkit.Maui. |
| 105 | + |
| 106 | +## Manual Updates |
| 107 | + |
| 108 | +If you need to manually add packages that aren't in `Versions.props`, you can edit the `cgmanifest.json` file directly. The update scripts preserve manually added entries and only update versions for packages it knows about. |
| 109 | + |
| 110 | +## Verifying the Package |
| 111 | + |
| 112 | +To verify that the cgmanifest.json file is included in the package: |
| 113 | + |
| 114 | +```bash |
| 115 | +# On macOS/Linux |
| 116 | +find ./artifacts/packages -name "Microsoft.Maui.Templates*.nupkg" | xargs -I{} unzip -l {} | grep cgmanifest.json |
| 117 | +
|
| 118 | +# On Windows |
| 119 | +foreach ($pkg in (Get-ChildItem -Path ./artifacts/packages -Filter "Microsoft.Maui.Templates*.nupkg")) { |
| 120 | + Add-Type -AssemblyName System.IO.Compression.FileSystem |
| 121 | + $zip = [System.IO.Compression.ZipFile]::OpenRead($pkg.FullName) |
| 122 | + $zip.Entries | Where-Object { $_.Name -eq "cgmanifest.json" -or $_.FullName -like "*cgmanifest.json" } |
| 123 | + $zip.Dispose() |
| 124 | +} |
| 125 | +``` |
0 commit comments