Masterarbeit/QuellCode/CentronERP/docs/operations/update-devexpress.md

# How to update DevExpress in c-entron<span>.NET

Before your start, **please** talk to everyone who manages one of the other projects (Outlook Add-In, Service-Board, Virtual Mail Assistant, c-entron Agent, etc.) to make sure they can all update as well.

We have documentation for the other projects (even if they have their own wikis) here to consolidate the update process.
Projects that do not have documentation here are usually updated by their respective developers (ServiceBoard etc.) or have documentation in their git repo.

This'll take you a few hours to complete and you cannot just do it halfway (leaving projects unable to update their c-entron dlls), so make sure to leave enough time and preferably start in the morning.  
*There __will__ be issues along the way, so be prepared!*

**Please note: this is a very delicate process and needs to be done very thoroughly. You cannot resonably test every project/ui to ensure it's working, so you'll have to make sure you do thing correctly.**  
**Errors or missing updates will probably only be noticed once people install (even worse if its only noticed once released to customers) and will usually result in bad/cryptic error messages.**  
**Always check all the changed files in your PRs, make sure everything that needs to be updated is updated and everything that doesnt need to be updated is not updated!**

## Branches & PRs

For consistency reasons it is advisable to use the same pattern of branchname, commitmessage and PR name everywhere.
 where | pattern | example (for Version 22.1.3)
--|--|--
Branch | \<shortsign>/update_devexpress_to_\<versionnumber> | hay/update_devexpress_to_2213
Commit | Update devexpress to \<versionnumber> | Update devexpress to 22.1.3
PR | same as the commit message

# [c-entron.Help](https://dev.azure.com/CentronSoftware/c-entron%20Help)

`Solution` > `ContextMenu` > `Manage NuGet Packages for Solution...` to update the NuGet packages.   

 Package|Projects
 --|--
`DevExpress.*` | `Centron.Help` 

Update the version number for `Centron.Help` in the `.csproj` file. Put your changes into a PR and self approve and complete it.
Copy the nuget-package to `/nugets` in c-entron<span>.NET and c-entron Outlook AddIn solution. 

[Reference PR](https://dev.azure.com/CentronSoftware/c-entron%20Help/_git/c-entron%20Help/pullrequest/12178)


# [c-entron<span>.NET](https://dev.azure.com/CentronSoftware/c-entron.NET)
 
There are two ways for you to do this, the offical way via nugget packages and the fast way.

 Package|Projects
 --|--
`DevExpress.*` | WPF, backend, webservice, shared **and Nexus (Blazor)** — all driven by the `NugetVersionDevExpress` variable (see below), you don't need to touch the individual `.csproj` files
`Centron.Help` | `Centron.WPF.UI`  

## Updating DevExpress dlls (single source)

The DevExpress version lives in **one** file: **`DevExpress.Version.props`** (repo root), which holds `<NugetVersionDevExpress>`. It is imported by both the root `Directory.Build.props` (WPF/backend/webservice/shared) and `src/nexus/Directory.Build.props` (Nexus/Blazor). Just change the value there — every `DevExpress.*` `PackageReference` uses `Version="$(NugetVersionDevExpress)"`.

> History: Nexus used to hard-code its 6 DevExpress versions in `src/nexus/CentronNexus/CentronNexus.csproj`. Those were switched to `$(NugetVersionDevExpress)` and Nexus's own `Directory.Build.props` imports the shared file (it does not inherit the root props), so a version change is now a single edit.

## Obtaining & updating c-entron.Help (do this FIRST — it is a hard blocker)

`Centron.WPF.UI` references the `Centron.Help` NuGet, and that package is compiled against a specific DevExpress version. If it lags behind, the WPF **markup compiler fails** with `MC1000 … Could not find assembly 'DevExpress.Data.v<OLD>'` — because the new DevExpress ships `DevExpress.Data.v<NEW>` and the old versioned assembly no longer exists.

So **ask the c-entron.Help maintainer for a new `Centron.Help.1.0.xxxx.x.nupkg` built against the new DevExpress version** (see the c-entron.Help section above / its own repo). Then:

1. Copy the new `Centron.Help.1.0.xxxx.x.nupkg` into `/nugets` and delete the old one.
2. Bump the `Centron.Help` `PackageReference` `Version` in `src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj`.
3. Clear the old extracted package from the NuGet cache if the version number was reused.

## Running tests

Some EndToEnd expected files contain RTF text with the DevExpress version that generated it, so they must be updated. This is **not just 2 tests** — there are roughly **20+** `*.expected.txt` files under `tests/Centron.Tests.EndToEnd/Tests/Settings/` and `tests/Centron.Tests.EndToEnd/Tests/Helpdesk/`.

You can either run the tests (`HelpdeskSettingsTests` / `SettingsTests`) so they regenerate, or bulk-replace the generator string across all files:

`..{\*\generator DevExpress Office File API/<OLD>.0}..`  
to   
`..{\*\generator DevExpress Office File API/<NEW>.0}..`

(e.g. old `25.2.6.0` → new `26.1.3.0`.) These files are UTF-8 **without BOM** and use **CRLF** — preserve both (use `perl -i -pe`, not an editor that rewrites line endings). Ignore the unrelated `9.2.x` strings (that is the c-entron ApplicationVersion) and any `*.actual.txt` (generated, gitignored).

## Breaking changes on major upgrades (e.g. 25.x → 26.x)

A minor bump is usually just the version + heatmaps. A **major** bump additionally tends to need:

- **Clear stale WPF build artifacts.** Delete `**/*_wpftmp.csproj` and the `obj`/`bin` folders of the WPF projects (`Centron.WPF.UI`, `Centron.WPF.UI.Extension`, `Centron.Controls`, `c-entron.misc.ConnectionManager`). They cache the old `DevExpress.*.v<OLD>` reference paths and keep reproducing the `MC1000` error even after the version bump.
- **Removed/changed API.** Fix compile errors from removed members. Example (26.1): `services.AddDevExpressBlazor(o => o.BootstrapVersion = BootstrapVersion.v5)` — `BootstrapVersion` was removed (Bootstrap 4 dropped, v5 is default) → use plain `services.AddDevExpressBlazor();` in `src/nexus/CentronNexus.Host/Program.cs`.
- **Version-hashed static assets.** DevExpress 26.1 no longer ships the internal `_content/DevExpress.Blazor/dx-blazor-<hash>.svg` sprite. Any custom `<use href="…#dx-editor-remove-tag">` (e.g. in `EmployeeTreeSelectionDropDown.razor`) breaks — replace with a self-contained inline SVG.
- Re-verify `wwwroot/css/devexpress-mods.css` overrides and any DevExpress `.Internal` namespace usages.
- **Restore first** (`dotnet restore Centron.sln`): a failed restore means the DevExpress feed/subscription does not cover the new (major) version — stop and clear that before anything else.

## Updating the heatmaps

The build might fail now, due to the installers not knowing about the new DevExpress DLLs.  
To fix this, execute the following command line in the root of the git directory:  
`dotnet run --project .\scripts\Centron.Scripts\Centron.Scripts.csproj -- update-installer-product-heat`  
This will update the `CentronProductHeat.wxs` and the `WebServiceProductHeat.wxs` (once for c-entron WS) to include the new missing files.  
*If only the minor version changes the heatmaps might not need an update.*

## Cleanup & PR

Updating the heatmaps re-touches the `Directory.Build.props` file (the `setup-versioning` step rewrites `<Version>` and `<GitCommitId>`). **Revert those two back** (`<Version>1.0.0.0</Version>`, empty `<GitCommitId>`). The DevExpress version itself now lives in `DevExpress.Version.props`, not here, so it is unaffected.

Now you can create the PR and wait for it to merge. Due to the changes to `.sln` and `.csproj` files, it'll need someone from the code-reviewer group.

[Reference PR](https://dev.azure.com/CentronSoftware/c-entron.NET/_git/c-entron.NET/pullrequest/12182)

# [c-entron Outlook AddIn](https://dev.azure.com/CentronSoftware/c-entron%20Outlook%20Add-In)

This only needs to be done in coordination with the maintainer of the Addin.

First you need to update the centron.Help nuget package, then update the packages themselves.   

 Package|Projects
 --|--
`DevExpress.*` | `Centron.OutlookAddin` & `Centron.Tickets`
`Centron.Help` | `Centron.OutlookAddin` & `Centron.Tickets`
`Centron.Controls` | `Centron.OutlookAddin` & `Centron.Tickets`

As before you also need to update the product heat. (reference c-entron<span>.NET)   

**Make sure to run the terminal as administrator, otherwise the build _will_ fail!**  
`dotnet run --project .\scripts\Centron.OutlookAddin.Scripts\Centron.OutlookAddin.Scripts.csproj -- update-installer-product-heat`  

[Reference PR](https://dev.azure.com/CentronSoftware/c-entron%20Outlook%20Add-In/_git/c-entron%20Outlook%20Add-In/pullrequest/9193?path=/src/Centron.Tickets/Centron.Tickets.csproj)

# Finishing touches

After you're done you should send a notification e-mail to all developers so they are aware of the update and can (if needed) update their own projects. 

*If you notice any changes to this process, then please update this documentation.*


# Further reading

## Error uploading nuget packages

### Error
`##[error]The nuget command failed with exit code(1) and error(System.AggregateException: One or more errors occurred. ---> System.Net.Http.HttpRequestException: Response status code does not indicate success: 403 (Forbidden - User 'ed8980f1-8a8a-4b5f-a522-5ca37b713bec' lacks permission to complete this action. You need to have 'AddPackage'. (DevOps Activity ID: 36B90B94-83BC-46CE-9349-5A4F110417E5)).`

### Fix
Ensure the nuget version in the build pipeline via the `NuGetToolInstaller@1` command. [Microsoft documentation](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/tool/nuget?view=azure-devops)  
If you get this error and have no idea what it means go talk to the grandmasters of the build pipelines and show them this