Altinn Studio CLI upgrade tool (#1408)

* basic install guide * frontend upgrade * v7->v8 migration guide
Altinn · Feb 20, 2024 · fac9a03 · fac9a03
1 parent 64b7815
commit fac9a03
Show file tree

Hide file tree

Showing 7 changed files with 272 additions and 79 deletions.
diff --git a/content/app/cli/_index.en.md b/content/app/cli/_index.en.md
@@ -0,0 +1,9 @@
+---
+title: Altinn Studio CLI
+description: Command line tool for upgrading Altinn Apps
+weight: 60
+---
+
+The Altinn Studio CLI is a command line tool for upgrading Altinn Apps. The tool is able to fix most breaking changes between version 7 and 8 of the Altinn.App.* NuGet packages, and version 3 and 4 of the Altinn App Frontend.
+
+{{<children />}}
diff --git a/content/app/cli/_index.nb.md b/content/app/cli/_index.nb.md
@@ -0,0 +1,9 @@
+---
+title: Altinn Studio CLI
+description: Kommandolinje-verktøy for oppgradering av Altinn-apper
+weight: 60
+---
+
+Altinn Studio CLI er et kommandolinje-verktøy for oppgradering av Altinn-apper. Verktøyet kan fikse de fleste breaking changes imellom versjon 7 og 8 av NuGet-pakkene Altinn.App.*, og imellom versjon 3 og 4 av Altinn App-Frontend.
+
+{{<children />}}
diff --git a/content/app/cli/install/_index.en.md b/content/app/cli/install/_index.en.md
@@ -0,0 +1,20 @@
+---
+title: Installation
+description: How to install the Altinn Studio CLI
+weight: 50
+---
+
+**Note**: The Altinn Studio CLI requires .Net 8.0 or later to be installed. See [Microsoft's documentation](https://dotnet.microsoft.com/en-us/download) to install .Net 8.0.
+
+To install the CLI, run the following command in your terminal:
+
+```bash
+dotnet tool install -g altinn.studio.cli
+```
+
+To verify that the installation was successful, run the following command:
+
+```bash
+altinn-studio --version
+```
+
diff --git a/content/app/cli/install/_index.nb.md b/content/app/cli/install/_index.nb.md
@@ -0,0 +1,19 @@
+---
+title: Installering
+description: Hvordan installere Altinn Studio CLI
+weight: 50
+---
+
+**NB**: Altinn Studio CLI krever at .Net 8.0 eller senere er installert. Se [Microsofts dokumentasjon](https://dotnet.microsoft.com/en-us/download) for installasjon av .Net 8.0.
+
+For å installere verktøyet, kjør følgende kommando i terminalen:
+
+```bash
+dotnet tool install -g altinn.studio.cli
+```
+
+For å verifisere at installasjonen var vellykket, kjør følgende kommando:
+
+```bash
+altinn-studio --version
+```
diff --git a/content/community/changelog/app-frontend/v4/migrating-from-v3/_index.en.md b/content/community/changelog/app-frontend/v4/migrating-from-v3/_index.en.md
@@ -2,13 +2,9 @@
 title: Migration from v3
 description: How to migrate from App-frontend v3 to v4
 weight: 50
+toc: true
 ---
 
-{{% notice warning %}}
-There are several breaking changes between App-frontend v3 and v4. 
-Make sure to read through the [list of breaking changes](/community/changelog/app-frontend/v4), and make the necessary changes throughout your app in addition to the changes below.
-{{% /notice %}}
-
 {{% notice info %}}
 As of writing this documentation, the latest release candidate of app-frontend v4 is `4.0.0-rc2`. Updated information
 [is available on GitHub](https://github.com/Altinn/app-frontend-react/releases). Before the release of v4.0.0 stable,
@@ -17,87 +13,137 @@ release candidate and you want to try out the new release, this URL will have to
 version is released, you can use `4` as the version number in the URLs and get the latest stable version automatically.
 {{% /notice %}}
 
-We are planning to release an upgrade tool that will automate the migration process and fix most breaking changes. 
-Until then, you can use the following guide to migrate manually.
+## Introduction
 
-### Manual migration
+This guide will help you migrate your app from using version 3 of App-frontend to version 4. 
+Since there are several breaking changes between these versions, it is very important that you test your app thoroughly after migrating. 
+There is currently no support in Altinn Studio for upgrading apps, so using the Altinn Studio CLI is the recommended way to migrate. 
+This will fix most of the breaking changes automatically, but you may still need to make some manual changes to your code.
 
-To use App-frontend v4 in your app, you need to change which version is referenced in your app's `Index.cshtml` file. 
-This file should be located in the `App/views/Home` folder. 
-In addition to changing the version, you should also remove the links to the third party CSS and font, as the font is now loaded by App-frontend itself, and the third party CSS is no longer used.
+## Migrate automatically using the Altinn Studio CLI
+
+{{% notice info %}}
+**Note**: You also need to upgrade the nuget packages to version 8.0. This can also be done using the Altinn Studio CLI. See [Migration from v7](/community/changelog/app-nuget/v8/migrating-from-v7) for more information.
+{{% /notice %}}
 
-Changes inside __&lt;head&gt;__:
-{{< code-title >}}
-App/views/Home/Index.cshtml
-{{< /code-title >}}
-```diff
-  <title>@ViewBag.Org- @ViewBag.App</title>
-
-  <link rel="icon" href="https://altinncdn.no/favicon.ico">
-- 
-- <!-- Third Party CSS -->
-- <link rel="stylesheet" href="https://altinncdn.no/toolkits/fortawesome/altinn-no-bold/0.1/css/embedded-woff.css">
-- <link rel="stylesheet" href="https://altinncdn.no/toolkits/fortawesome/altinn-no-regular/0.1/css/embedded-woff.css">
-- <link rel="stylesheet" href="https://altinncdn.no/toolkits/fortawesome/altinn-studio/0.1/css/embedded-woff.css">
-- 
-- <!-- Fonts -->
-- <link href="https://altinncdn.no/fonts/altinn-din/altinn-din.css" rel="stylesheet">
-
-  <!-- Runtime CSS -->
-- <link rel="stylesheet" type="text/css" href="https://altinncdn.no/toolkits/altinn-app-frontend/3/altinn-app-frontend.css">
-+ <link rel="stylesheet" type="text/css" href="https://altinncdn.no/toolkits/altinn-app-frontend/4.0.0-rc2/altinn-app-frontend.css">
+The Altinn Studio CLI is a command line tool for upgrading Altinn Apps. The tool is able to upgrade and fix most breaking changes between version 3 and 4 of the Altinn App-frontend.
+
+### Verify that you have the latest version of the Altinn Studio CLI
+
+If you do not have the CLI installed, you can install it by following the instructions in the [installation guide](/app/cli/install).
+
+<!-- TODO: Uncomment and update version number when a new version gets released
+Make sure you are using at least version 1.0.0 of the altinn studio cli. You can check the version by running:
+
+```bash
+altinn-studio --version
 ```
 
-Changes inside __&lt;body&gt;__:
-{{< code-title >}}
-App/views/Home/Index.cshtml
-{{< /code-title >}}
-```diff
-  <div class="flex-column d-flex media-body">
-
-  <script>
-    function loadScript() {
-      var appId = window.location.pathname.split('/');
-      window.reportee = document.cookie.replace(/(?:(?:^|.*;\s*)AltinnPartyId\s*\=\s*([^;]*).*$)|^.*$/, "$1");;
-      window.org = appId[1];
-      window.app = appId[2];
-    }
-  </script>
-  <div id="root" class="media-body flex-column d-flex"></div>
-  <script>
-    loadScript();
-  </script>
-  </div>
-
-- <script src="https://altinncdn.no/toolkits/altinn-app-frontend/3/altinn-app-frontend.js"></script>
-+ <script src="https://altinncdn.no/toolkits/altinn-app-frontend/4.0.0-rc2/altinn-app-frontend.js"></script>
+If you have an older version, you can update it by running:
+
+```bash
+dotnet tool update -g altinn.studio.cli
 ```
 
-It's optionally also possible to change the `$schema` reference in layout files to get the latest suggestions
-and validations for layout configuration. This is not required for v4 to work, but is recommended when developing
-applications locally, as you'll get the most up-to-date suggestions and validations in Visual Studio Code.
-{{< code-title >}}
-App/ui/*/layouts/*.json
-{{< /code-title >}}
-
-```diff
-  {
--   "$schema": "https://altinncdn.no/schemas/json/layout/layout.schema.v1.json",
-+   "$schema": "https://altinncdn.no/toolkits/altinn-app-frontend/4.0.0-rc2/schemas/json/layout/layout.schema.v1.json",
-    "data": {
-      "layout": [
-        {
-          "id": "nav1",
-          "type": "NavigationBar"
-          ...
-        },
-        ...
-      ]
-    }
-  }
+-->
+
+### Run the upgrade command
+
+First, navigate to the root folder of your app in your terminal. There are several optional arguments you can use with the `upgrade frontend` command. You can see all the available options by running:
+
+```bash
+altinn-studio upgrade frontend --help
 ```
 
-{{% notice warning %}}
-__Note__: These are only the changes necessary to switch frontend version, you also need to fix any [breaking changes](/community/changelog/app-frontend/v4) affecting your app, including upgrading the nuget packages to version 8.0.
-{{% /notice %}}
+The default options should work for most apps, but you may need to specify some options if you have a non-standard project structure. 
+If some of the options are not correct, the CLI should print an error message explaining what went wrong.
+
+It is recommended to have a clean working tree before running the upgrade command. 
+This means that you should commit or stash any changes you have made to your code before running the command. 
+That way you can easily see what changes the CLI made to your code, as well as reset and try again if something went wrong.
+
+When you are ready to upgrade, run the following command:
+
+```bash
+altinn-studio upgrade frontend
+```
+
+The CLI will then make the necessary changes to your code to upgrade it to version 4 of App-frontend. The CLI will also print warnings and errors if it encounters any problems during the upgrade process, make sure to read these carefully.
+
+## Migrate manually
+
+To use App-frontend v4 in your app, you need to change which version is referenced in your app's `Index.cshtml` file. 
+This file should be located in the `App/views/Home` folder. 
+In addition to changing the version, you should also remove the links to the third party CSS and font, as the font is now loaded by App-frontend itself, and the third party CSS is no longer used.
+
+1. Changes inside __&lt;head&gt;__:
+    <br><br>
+    {{< code-title >}}
+    App/views/Home/Index.cshtml
+    {{< /code-title >}}
+    ```diff
+      <title>@ViewBag.Org- @ViewBag.App</title>
+
+      <link rel="icon" href="https://altinncdn.no/favicon.ico">
+    - 
+    - <!-- Third Party CSS -->
+    - <link rel="stylesheet" href="https://altinncdn.no/toolkits/fortawesome/altinn-no-bold/0.1/css/embedded-woff.css">
+    - <link rel="stylesheet" href="https://altinncdn.no/toolkits/fortawesome/altinn-no-regular/0.1/css/embedded-woff.css">
+    - <link rel="stylesheet" href="https://altinncdn.no/toolkits/fortawesome/altinn-studio/0.1/css/embedded-woff.css">
+    - 
+    - <!-- Fonts -->
+    - <link href="https://altinncdn.no/fonts/altinn-din/altinn-din.css" rel="stylesheet">
+
+      <!-- Runtime CSS -->
+    - <link rel="stylesheet" type="text/css" href="https://altinncdn.no/toolkits/altinn-app-frontend/3/altinn-app-frontend.css">
+    + <link rel="stylesheet" type="text/css" href="https://altinncdn.no/toolkits/altinn-app-frontend/4.0.0-rc2/altinn-app-frontend.css">
+    ```
+2. Changes inside __&lt;body&gt;__:
+    <br><br>
+    {{< code-title >}}
+    App/views/Home/Index.cshtml
+    {{< /code-title >}}
+    ```diff
+      <div class="flex-column d-flex media-body">
+
+      <script>
+        function loadScript() {
+          var appId = window.location.pathname.split('/');
+          window.reportee = document.cookie.replace(/(?:(?:^|.*;\s*)AltinnPartyId\s*\=\s*([^;]*).*$)|^.*$/, "$1");;
+          window.org = appId[1];
+          window.app = appId[2];
+        }
+      </script>
+      <div id="root" class="media-body flex-column d-flex"></div>
+      <script>
+        loadScript();
+      </script>
+      </div>
 
+    - <script src="https://altinncdn.no/toolkits/altinn-app-frontend/3/altinn-app-frontend.js"></script>
+    + <script src="https://altinncdn.no/toolkits/altinn-app-frontend/4.0.0-rc2/altinn-app-frontend.js"></script>
+    ```
+3. It's optionally also possible to change the `$schema` reference in layout files to get the latest suggestions
+    and validations for layout configuration. This is not required for v4 to work, but is recommended when developing
+    applications locally, as you'll get the most up-to-date suggestions and validations in Visual Studio Code.
+    <br><br>
+    {{< code-title >}}
+    App/ui/*/layouts/*.json
+    {{< /code-title >}}
+    ```diff
+      {
+    -   "$schema": "https://altinncdn.no/schemas/json/layout/layout.schema.v1.json",
+    +   "$schema": "https://altinncdn.no/toolkits/altinn-app-frontend/4.0.0-rc2/schemas/json/layout/layout.schema.v1.json",
+        "data": {
+          "layout": [
+            {
+              "id": "nav1",
+              "type": "NavigationBar"
+              ...
+            },
+            ...
+          ]
+        }
+      }
+    ```
+4. Fix any [breaking changes](/community/changelog/app-frontend/v4) affecting your app, including upgrading the nuget packages to version 8.0.
diff --git a/content/community/changelog/app-nuget/v8/migrating-from-v7/_index.en.md b/content/community/changelog/app-nuget/v8/migrating-from-v7/_index.en.md
@@ -0,0 +1,84 @@
+---
+title: Migration from v7
+description: How to migrate from v7 to v8
+weight: 50
+toc: true
+---
+
+{{% notice info %}}
+As of writing this documentation, the latest preview release of v8 is `8.0.0-preview.16`. Updated information
+[is available on GitHub](https://github.com/Altinn/app-lib-dotnet/releases).
+{{% /notice %}}
+
+## Introduction
+
+This guide will help you migrate your app from using version 7 of the app nugets to version 8. 
+There is currently no support in Altinn Studio for upgrading apps, so using the Altinn Studio CLI is the recommended way to migrate. 
+
+## Migrate automatically using the Altinn Studio CLI
+
+The Altinn Studio CLI is a command line tool for upgrading Altinn Apps. The tool is able to upgrade and fix most breaking changes between version 7 and 8 of the app nugets.
+
+### Verify that you have the latest version of the Altinn Studio CLI
+
+If you do not have the CLI installed, you can install it by following the instructions in the [installation guide](/app/cli/install).
+
+<!-- TODO: Uncomment and update version number when a new version gets released
+Make sure you are using at least version 1.0.0 of the altinn studio cli. You can check the version by running:
+
+```bash
+altinn-studio --version
+```
+
+If you have an older version, you can update it by running:
+
+```bash
+dotnet tool update -g altinn.studio.cli
+```
+
+-->
+
+### Run the upgrade command
+
+First, navigate to the root folder of your app in your terminal. There are several optional arguments you can use with the `upgrade backend` command. You can see all the available options by running:
+
+```bash
+altinn-studio upgrade backend --help
+```
+
+The default options should work for most apps, but you may need to specify some options if you have a non-standard project structure. 
+If some of the options are not correct, the CLI should print an error message explaining what went wrong.
+
+It is recommended to have a clean working tree before running the upgrade command. 
+This means that you should commit or stash any changes you have made to your code before running the command. 
+That way you can easily see what changes the CLI made to your code, as well as reset and try again if something went wrong.
+
+1. Before running the upgrade you need to first restore any dependencies:
+    ```bash
+    dotnet restore
+    ```
+2. When you are ready to upgrade, run the following command:
+    ```bash
+    altinn-studio upgrade backend
+    ```
+
+The CLI will then make the necessary changes to your code to upgrade it to version 8. The CLI will also print warnings and errors if it encounters any problems during the upgrade process, make sure to read these carefully.
+
+## Migrate manually
+
+1. To migrate manually from v7 to v8, you need to upgrade the nuget packages in your `App.csproj` file to version `8.0.0-preview.16`.
+    <br><br>
+    {{< code-title >}}
+    App/App.csproj
+    {{< /code-title >}}
+    ```diff
+    -   <PackageReference Include="Altinn.App.Api" Version="7.15.3">
+    +   <PackageReference Include="Altinn.App.Api" Version="8.0.0-preview.16">
+            <CopyToOutputDirectory>lib\$(TargetFramework)\*.xml</CopyToOutputDirectory>
+        </PackageReference>
+    -   <PackageReference Include="Altinn.App.Core" Version="7.15.3" />
+    +   <PackageReference Include="Altinn.App.Core" Version="8.0.0-preview.16" />
+            <CopyToOutputDirectory>lib\$(TargetFramework)\*.xml</CopyToOutputDirectory>
+        </PackageReference>
+    ```
+2. Next, you need to fix the breaking changes in your code. See the [changelog for v8](/community/changelog/app-nuget/v8/#breaking-changes) for more information.
diff --git a/content/community/changelog/app-nuget/v8/migrating-from-v7/_index.nb.md b/content/community/changelog/app-nuget/v8/migrating-from-v7/_index.nb.md
@@ -0,0 +1,6 @@
+---
+title: Migrering fra v7
+description: Hvordan migrere fra v7 til v8
+weight: 50
+---
+