アップグレード

Web SDK のバージョンを更新する

バージョン 1019.x.x 以降、Web SDK はセマンティック バージョンを採用しています。つまり、メジャーバージョンアップ（例：1019 から 1020）には重大な変更が含まれる可能性がありますが、マイナーバージョンや修正バージョンの更新によってアプリケーションが動作しなくなることはありません。そのため、マイナーバージョンや修正バージョンに更新するのは安全ですが、メジャーバージョンに更新する場合は移行が必要になる可能性があります。

現在のところ、移行の最も簡単な方法は、gitでの差分を比較することです。

準備

データをバックアップしたり、コードの差分を確認するために、ソース管理システム（SCM）を使用することをお勧めします。SCM をまだ使用していない場合は、git を使用して変更を保存する方法を紹介していますので、次をご覧ください。すでに SCM を使用している場合、または SCM を使用したくない場合は、次のセクションに進むことができます。SCM を使用しない場合は、更新を実行する前にアプリケーションをバックアップしてください。

システムに git がインストールされていることを確認します。次にターミナルを開き、以下のコマンドを実行します。

cd <<path/to-you-app>>
git init
git add .
git commit -m "init commit"

これで、コードは .git フォルダに保存されているローカルの git リポジトリにコミットされます。次に、Web SDKを更新する方法を説明します。更新後に git を使用しない場合は、.git フォルダを消去してください。

更新

Web SDK を更新するには、必要なバージョンで新しいアプリケーションを作成し、ファイルをコピーする必要があります。すると、差分によってマージの競合が発生する可能性のある場所が示されます。マージ前にマージの競合を修正してください。

ng new cockpit
cd cockpit
ng add @c8y/websdk 

スキャフォールドするアプリケーションの新しいバージョンを選択すると、最新のスキャフォールディング ファイルが取得されます。これらのファイルを、以前にチェックインしたソリューションにコピーすると、バージョン間の差異を確認できます。

変更を再反映するための差分

git diff ツールは、アップグレードに伴って行われた変更と、以前にカスタマイズした箇所を再反映するのに便利です。次のスクリーンショットでは、Visual Studio Code を使用して変更を特定しています。これは、git diff ツール（大概の IDE は git 差分もサポートしています）がうまく統合されているためです。

このツールを使用すると、アップグレードで変更されたファイルと、カスタム変更を再適用する必要がある場所を簡単に比較できます。この場合、MyCustomModule はアップグレードの app.module.ts にのみ反映する必要があります。この変更が完了すると、更新を確認できます。

更新の検証

バージョンの更新が機能したかどうかを確認するには、通常、最初にローカルで実行することをお勧めします。したがって、最初に依存関係を再度インストールする必要があります。現在の node_modules ディレクトリを削除し、npm install（または yarn）を再度実行して依存関係を更新してください。その後、npm start でアプリケーションを起動します。ログイン後、ユーザー名をクリックすると、現在の UI バージョンを確認できます。

すべてが予想通りに動作した場合、npm run deploy コマンドを実行して、アプリケーションをデプロイできます。

結論

特に app.module.ts に多くの変更がある場合、更新プロセスは少し注意が必要な場合があります。ただし、git と Visual Studio Code を使用すると、視覚的な違いがこのタスクの実行に役立つ場合があります。また、独自の Angular のカスタマイズはモジュールに入れ、必要な場合にのみ app.module.ts に変更を加えることをお勧めします。

Angular CLI 10.19.x.x 以前

純正の Angular を開発する際には、Angular CLI（ng-cli）プロジェクトを作成し、Things Cloud CLI を追加できます。
この機能は、次のバージョンで利用可能です。

• Angular 7： バージョン 10.4.2.0 からサポート
• Angular 8： バージョン 10.5.9.0 からサポート
• Angular 11： バージョン 10.10.4.0 からサポート
• Angular 12： バージョン 10.11.45.0 からサポート
• Angular 14： バージョン 10.15.132.0 からサポート
• Angular 15： バージョン 10.18.157.0 からサポート

Angular CLI のインストール

手順 に従って @c8y/cli をグローバルにインストールします。

npm install -g @angular/cli@v8-lts

新しいプロジェクトの作成

ng new my-first-iot-project
cd my-first-iot-project

Things Cloud CLIの追加

ng add @c8y/cli

アプリケーションの実行

ng serve

ブラウザで http://localhost:4200/ を開き、新しいアプリケーションの実行を確認します。

package.jsonファイル内でアプリケーションオプション を構成し、LESS または CSS のカスタム変数を使用してブランディング をカスタマイズできます。

C8Y コマンドラインツール (CLI)

アプリケーションのブートストラップ、実行、デプロイをサポートするために CLI（コマンドライン インターフェース）が用意されています。この CLI は cumulocity-node-tools の後継です。2 つの CLI の競合を防ぐために、CLI では c8y の代わりに c8ycli という新しいコマンドを使用しています。次のように npm でインストールできます。

npm install -g @c8y/cli

@c8y/cli をグローバルにインストールしたくない場合は、npx コマンドで実行することもできます。例えば、次のコマンドを実行することで、新しいプロジェクトをすばやくスキャフォールディングすることができます。

npx @c8y/cli new

新しいプロジェクトはローカルの @c8y/cli を作成します。そのディレクトリに移動し、次のコマンドを実行することでプロジェクトを実行することができます。

npm install && npx c8ycli serve

serve コマンドはローカル開発サーバーを起動します。このコマンドは 2 つの重要なフラグをサポートしています。

• -u： -u パラメータは、すべての API リクエストがプロキシされる Things Cloud インスタンスを指定します。これは、設定された Things Cloud インスタンスから実際にデータが取得されることを意味します。
• -p： 使用するポートです。定義されていない場合は 9,000 番ポートが使われます。すでにこのポートでサーバーが動いている場合、コマンドは失敗します。アプリケーションは http://localhost:<<port>>/apps/<<your-application-name>>/ という URL で提供されます。 ヒント：ターミナルで「Ctrl」キーを押しながら URL をクリックしてください。

使用方法

c8ycli [options] [command]

オプション

    -u, --url <url>                 リモートインスタンスの URL
    --version                       バージョン番号の表示
    -h, --help                      使用方法の表示

コマンド

new 以外のすべてのコマンドは、glob patterns の配列を受け取ります。これらはディレクトリまたはエントリポイント マニフェストによって解決されます。

    new [name] [template]                   新しいアプリケーションまたは既存のアプリケーション拡張のためにフォルダを作成する
    serve [options] [appPaths...]           ローカルの開発サーバーを起ち上げる
    build [options] [appPaths...]           特定のアプリケーションをビルドする
    deploy [options] [appPaths...]          特定のパスからアプリケーションをデプロイする
    locale-extract [options] [srcPaths...]  翻訳用のすべての文字列を抽出し、定義済みのフォルダへ .po ファイルを出力する

new コマンド

c8ycli new [name] [template] では空のアプリケーションの作成、または既存のアプリケーション（コックピット、デバイス管理、管理）を拡張できます。既存のアプリケーションを拡張するには、次のように、既存のアプリケーション名を [name] および [template] として使用します。

$ c8ycli new cockpit cockpit

c8ycli new コマンドは、[name] および [template] オプションなしでも提供できます。この場合、次の手順に従ってインターフェースを介してプロセスを完了してください。

ステップ 1：

? Enter the name of the project: (my-application)　

最初の手順では、プロジェクト名を求められます。プロジェクト名が入力されていない場合、デフォルトの my-application が使用されます。

ステップ 2：

? Which base version do you want to scaffold from? (Use arrow keys)
> 1010.0.X (latest)
> 1011.X.0 (next)
> 1011.0.X
> 1009.0.X
> 1007.0.X
> 1006.0.X
> other

ステップ 2 では、スキャフォールディングとなるバージョンを選択する必要があります。インターフェースには、最新の CD バージョン（latest）と、それ以前の年次リリースが表示されます。さらに、other オプションを選択することで、バージョンを手動で入力することができます。

ステップ 2（other）：

? Enter the desired version:

この手順では、希望するバージョンを 1010.0.0 のように手動で入力する必要があります。

ステップ 3：

? Which base project do you want to scaffold from?
  administration
  application
  cockpit
  devicemanagement
  hybrid
  tutorial

最後の手順では、スキャフォールディングとなるプロジェクトを選択する必要があります。

アプリケーション オプション

アプリケーション オプションは --app.<option>=<value> で定義されます。これらは [appPaths...] に存在するすべてのアプリケーションに適用されます。

    --app.name="My Application"
    --app.key=myapp-key
    --app.contextPath=myapplication
    --app.brandingEntry="./branding/mybranding.less"

Webpack オプション

Webpack オプションは --env.<option>=<value> により定義されます。これらは直接 Webpack の設定へ渡されます。

    --env.mode="production"
    --env.hmr

Angular 16 から Angular 17へのアップグレード

Angular 17 はバージョン 1020.0.0 からサポートされています。アプリケーションを実行する前に、次の設定変更が必要です。

• package.json 内のすべての @c8y 依存関係をバージョン 1020.x.x に更新します。
• src/polyfills.ts ファイル内の import 'zone.js/dist/zone' を import 'zone.js' に置き換えます。
• angular.json ファイル内のすべての "browserTarget" の出現を "buildTarget" に置き換えます。
• ng update @angular/core@17 @angular/cli@17 コマンドを実行して、Angular Core と CLI をバージョン 17 に更新します。
• ngx-bootstrap をバージョン 12.0.0 に更新します。
• @angular/cdk をバージョン 17.x.x に更新します。
• src/main.ts ファイル内の loginOptions の参照をすべて削除します。loginOptions 関数は、現在 loadOptions 関数の一部として内部で呼び出されています。
• package.json に @c8y/options パッケージを devDependency として追加します。

Angular 17 から Angular 18 へのアップグレード

Angular 18 はバージョン1021.0.0からサポートされています。アプリケーションを実行する前に、次の設定変更が必要です。

• package.json 内のすべての @c8y 依存関係をバージョン 1021.x.x に更新します。
• ng update @angular/core@18 @angular/cli@18 コマンドを実行して Angular Core と CLI をバージョン 18 に更新します。
• ngx-bootstrap をバージョン 18.0.0 に更新します。
• @angular/cdk をバージョン 18.x.x に更新します。
• brandingEntry アプリケーション オプションを使用して、アプリケーションのグローバルスタイルをカスタマイズすることはできなくなりました。 代わりに、グローバルスタイルは Angular が提供するメカニズム を介して指定する必要があります。 これまで cumulocity.config.ts ファイルで brandingEntry を使用していなかった場合、今後は angular.json ファイルの styles 配列で @c8y/style/main.less ファイルを参照する必要があります。 これまで cumulocity.config.ts で brandingEntry を使用していた場合、今後は angular.json ファイルの styles 配列で同じファイルを参照する必要があります。 cumulocity.config.ts ファイルから brandingEntry を削除する必要があります。
• Node.js、TypeScript、RxJS: バージョン互換性
• Angular 18 アップグレードガイドに従ってください： バージョン 18 への更新

Angular 15 から Angular 16 および NG CLI へのアップグレード

Angular 16 はバージョン 1019.0.0 からサポートされています。最新バージョン 1019.0.0 では、Web SDK は ng-cli を使用するよう移行され、c8ycli の開発は終了しました。

この移行は業界標準に準拠し、開発者が Web SDK をより便利に活用できるようにすることを目的としています。既存の Web SDK プロジェクトを ng-cli に移行したい Angular 開発者の方は、次のステップバイステップガイドに従って手順をご確認ください。

1. ng-cli プロジェクトを作成する

最初に、適切なバージョンの ng-cli をダウンロードし、ng new コマンドを使用してプロジェクトをスキャフォールディングします。このプロセスでは、既存のプロジェクト名を使用してください。

2. アプリを構築するために @c8y/websdk を追加する

ng add @c8y/websdk を実行して、@c8y/websdk を ng-cli プロジェクトに統合します。正しいプロジェクトタイプとしてapplication または hybrid を選択してください。

3. ソースファイルをコピーする

すべてのコンポーネント、ディレクティブ、モジュール、テスト、サービスファイルを新しい ng-cli プロジェクトにコピーします。また、アセットなどの非標準ファイルも新しいプロジェクトに移行します。

4. package.json を調整する

依存関係を確認して比較することで package.json ファイルを更新します。カスタム依存関係を追加する際は、新しい依存関係が保持されていることを確認してください。「c8y」プロパティオブジェクトを除く、元のプロジェクトからの他のプロパティを更新します。すべてのスクリプトで c8ycli ではなく ng を使用するように変更し、「server」という単語はすべて「serve」に名前変更します。

5. cumulocity.config.ts を調整する

package.json ファイルにあるすべての「c8y.application」プロパティを新しい cumulocity.config の runTime オブジェクトに転送します。JavaScript としてフォーマットし、エラーがないか確認します。フェデレーション共有が十分かどうかを確認し、そうでない場合は必要に応じて調整します。一部のオプションは buildTime に移動する必要があるかもしれません。

6. tsconfig ファイルを確認する

プロジェクトのニーズに合わせて tsconfig ファイルを確認し、調整します。デフォルトで有効になっている noPropertyAccessFromIndexSignature や noImplicitReturns などの特定の厳格な構成を無効にする必要がある場合があります。

7. 依存関係をインストールし、確認する

依存関係をインストールし、すべてのピア依存関係が一致していることを確認します。Angular 16 でシームレスに動作させるために変更が必要な依存関係があれば、更新します。

8. Angular アップデートガイドを確認する

ng-cli は Angular 16 を使用しているため、互換性を確認するには Angular アップデートガイド を確認してください。

9. 起動する

最後に、npm start または npx ng <<name-of-your-app>> を使用してアプリケーションを実行してみてください。コンパイルエラーがないか確認し、問題があれば解決します。Angular 16 の場合、モジュール内のすべての entryComponents 配列を削除します。これらの配列はバージョン 15 で非推奨となり、バージョン 16 で削除されました。

よくある落とし穴

• rxjs の Subject が値なしでのみ出力する必要がある場合、void で正しく型指定されていることを確認してください。
• コードからすべての entryComponents を削除してください。
• @c8y/devkit/dist/options パッケージから ApplicationOptions をインポートし、不要なバンドルを避けるために型のみをインポートすることを検討してください（import type from '@c8y/devkit/dist/options';）。

Angular 14 から Angular 15 へのアップグレード

Angular 15 はバージョン 1018.157.0 からサポートされています。アプリケーションを実行する前に、次の設定変更が必要です。

• すべての @angular/* 依存関係を 15.2.7 に更新します。
• TypeScript をバージョン 4.9.5 に更新します。
• Angular 15 アップグレードガイドに従ってください：バージョン15への更新
• Nodeバージョン ^14.20.0 || ^16.13.0 || ^18.10.0 を使用してください。
• node_modules を削除し、再インストールします。
• トークンフックは非推奨となり、関数フックに置き換えられました。トークンフックがどの関数フックに移行されたかは、次の表でご確認ください。

非推奨フックトークンと代替

Angular 12 から Angular 14 へのアップグレード

Angular 14 はバージョン 1015.132.0 からサポートされています。アプリケーションを実行する前に、次の設定変更が必要です。

• すべての @angular/* 依存関係を 14.0.6 に更新します。
• TypeScript 4.6 が Angular で必要なため、TypeScript をバージョン 4.7.4 に更新します。
• Angular 14 のアップグレードガイドに従ってください：バージョン14への更新
• 新しい開発依存関係をインストールします。
  • "html-loader"： "4.1.0"
  • "style-loader"： "3.3.1"
• Node バージョン 14 を使用します。
• node_modules を削除して、再インストールします。

Angular 11 から Angular 12 へのアップグレード

Angular 12 は、バージョン 10.11.45.0 からサポートされています。アプリケーションを実行する前に、次の構成変更が必要です。

• すべての @angular/* 依存関係を 12.2.x に更新します。
• TypeScript 4.2 が Angular で必要なため、TypeScript をバージョン 4.2.x に更新します。
• Angular 12 のアップグレードガイドに従ってください：バージョン 12 への更新
• Node バージョン 14 を使用します。

IVYを有効にする方法

Ivy は、アプリケーションの速度を向上させ、開発を容易にする Angular アプリケーションの新しいレンダリングエンジンです。Ivy を有効にすることは必須ではありませんが、古いビューエンジンは非推奨であるため、有効にすることをお勧めします。

更新中に：

• デフォルト設定のため tsconfig.json を編集して enableIvy を true に設定するか、削除してください。

    "angularCompilerOptions": {
        "enableIvy": true
  }

• package.json を編集して、postinstall フックを追加します。

    "scripts": {
        ...
    "postinstall": "ngcc"
  }

• node_modules を削除し、再インストールします。ngcc が動作している場合、すべての依存関係をインストールした後 コンパイル手順が表示されます。
• Jest（JavaScript Testing Framework）を使用する場合、Jest - Angular IVY で設定を確認してください。

Angular 11 へのアップグレード

Angular 11 はバージョン 10.10.4.0 からサポートされています。AOT と Ivy はまだサポートされていません。アプリケーションを実行する前に、以下の設定変更が必要です。

• @angular/compiler-cli をバージョン 11.2.9 以下に修正します。
• angular.json ファイルから index プロパティを削除します（存在する場合）。また、ng-cli からの --index フラグはサポートされていません。カスタム index.html ファイルは ApplicationOptions の indexTemplate で渡すことができます。