アップグレード

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

バージョン: 10.6.0.0 | パッケージ: @c8y/cli, @c8y/apps, @c8y/ngx-components

以前のバージョンのWeb SDKでビルドしたUIは、ビルド時のバージョンに固定されています。 プラットフォームの更新によって UI のバージョンが更新されませんが、すべての API は後方互換性があるので、新しいバックエンドで実行されている UI でも新しい機能を使えるようになります。 そのためUIまたはWeb SDKの新しい機能を使用する必要がある場合はほとんど、更新が有効です。したがって、新しいアプリケーションをビルドしてプラットフォームにデプロイする必要があります。 このレシピでは、そのためのベストプラクティスについて説明します。

準備

データをバックアップしたり、コードの差分を確認するために、ソース管理システム（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を更新するには、スキャフォールディングで使用する new コマンドを使用します。

c8ycli new <<app-name>> <<cockpit|devicemanagement|administration>> -a @c8y/apps@<<version>>

例えば、現在の作業ディレクトリがThings Cloudのコックピットアプリケーションをベースにした「my-cockpit」というアプリケーションで、バージョン10.6.2.0に更新する場合は、次のコマンドを実行する必要があります。

cd ..
c8ycli new my-cockpit cockpit -a @c8y/apps@1006.2.0

このコマンドは、特定のバージョンで新しいアプリケーションをビルドするために使用されるファイルをコピーします。 現在、以下のファイルが上書きされています。

• app.module.ts: Angularモジュールは、カスタムAngularモジュールをインポートするためにアプリケーションによって調整される可能性があります。
• index.ts: 最初に呼び出されるブートストラッピングファイルです。通常、このファイルは変更されません。
• ng1.ts: AngularJSのインポートは、AngularJSプラグインを追加または削除するように調整されている可能性があります。
• package.json: npmの依存性、アプリケーションのオプション、および名前はこのファイルに格納されます。これは、異なるオプションや異なる依存関係が使用された場合などに変更される可能性が非常に高くなります。
• tsconfig.json: TypeScriptの構成ファイルです。通常、このファイルは変更されません。
• angular.json: Angularプロジェクトでビルドや開発ツールに使用するデフォルトの設定ファイルです。

これらは、その記事のバージョンに基づく更新によって上書きされるファイルです。 この一覧は、今後のバージョンで変更される可能性があります。 次に、これらのファイルについて以前に加えた変更を再適用する必要があります。 それには、git diffツールがとても役立ちます。

変更を再反映するために差分を確認する

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

このツールを使用すると、アップグレードで変更されたファイルと、カスタム変更を再適用する必要がある場所を簡単に比較できます。 この場合、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 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 を使用して渡すことができます。

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

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

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

IVY を有効にする方法

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

更新中に：

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

    "angularCompilerOptions": {
        "enableIvy": true
  }

• Package.json を編集して、 postinstall を追加します。

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

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

アプリケーションの移行

このセクションはプラグイン用 AngularJS SDK を用いてプラグインを開発したことがある、もしくは既存のデフォルトアプリケーションを拡張したい開発者を対象としています。

以下のコンセプトを理解する必要があります。

• 付録: 移行履歴: どのSDKをいつ使うか説明しています。
• アップグレード: どのバージョンから新しいSDKが使用できるか説明しています。
• C8Yコマンドラインツール（CLI） : 新しいツールをインストールできるようにします。

ハイブリッドアプリケーションをセットアップする

ハイブリッドアプリケーションでは、同時にAngularJSとAngularを使用できます。AngularJSで記述された移行されていないプラグインをAngularの文脈で使用できるようになります。テンプレートとしてコックピット、デバイス管理、管理などのデフォルトアプリケーションを使用する場合、CLI は自動的にハイブリッドアプリケーションをセットアップします。使用コマンドは c8ycli new <your-app-name> <template-name> です。

例えば、既定のコックピットを上書きするには以下を実行します。

c8ycli new cockpit cockpit

このコマンドを実行すると、以下のファイルを含む単純なファイル構造ができ上がります。

• app.module.ts: AngularのルートをフックできるAngularのエントリーモジュール。Things Cloudのアプリケーションでは、ルート要素へのアクセスは不可能なため、編集可能なルートテンプレート（index.html）は存在しません。
• package.json: 依存関係やアプリケーション自体の情報を記述します。フラグ c8y.upgrade: true はwebpackプラグインにAngularJSプラグインを許可するよう伝える役割があります。
• ng1.ts: コックピットアプリケーション用のデフォルトのAngularJSプラグイン。
• index.ts: ハイブリッドアプリケーションのブートストラップをセットアップします。
• polyfills.ts: IE11で実行するポリフィルをセットアップします。
• tsconfig.json: TypeScriptの設定用ファイル。

AngularJSプラグインのインポート

アプリケーションへカスタムプラグインを統合するには、はじめにプラグインをインポートするハイブリッドアプリケーションをセットアップする必要があります。そして、ハイブリッドアプリケーションにプラグインをコピーし、 ng1.ts ファイルでプラグインの cumulocity.json をimport文で参照してください。

import 'my-custom-plugin/cumulocity.json';

Webpackはマニフェストファイルを読み取り、コンテンツをimportを必要とするCommonJSへ変換します。これにより、プラグインがロードされアプリケーションに適用されます。

カスタムブートストラップとアップグレード

app.module.ts ファイルでは、HybridAppModule に存在する以下のコードを用いてハイブリッドアプリケーションをブートストラップしています。

import { UpgradeModule as NgUpgradeModule } from '@angular/upgrade/static';
import { ng1Modules } from './ng1';

export abstract class HybridAppModule {
  ng1Modules = ng1Modules;
  protected upgrade: NgUpgradeModule;

  ngDoBootstrap() {
    (window as any).bootstrap();
    this.upgrade.bootstrap(document.getElementById('app'), this.ng1Modules, { strictDi: false });
  }
}

このモジュールはアップグレードモジュールをブートストラップするだけでなく、Angularアプリケーションを初期化します。

app.module.ts ではブートストラップを制御できます。例えば、ブートストラップされたng1モジュールに別のモジュールを追加できます。

constructor() {
  this.ng1Modules.push('my-custom-module');
}

上記のコードは my-custom-module も読み込みます。上記のコードを用いると ngDoBootstrap() 関数をアプリケーションのニーズに応じて上書きできます（例: Angularの文書に示されているupgrade, downgradeのAngularのserviceなど）。