JavaScript オブジェクトモデル (JSOM) を使用したProject Online アドインの開発

2023-04-04

この記事では、Project Online Microsoft Project Onlineエクスペリエンスを強化するためのアドイン開発について説明します。開発プロジェクトは、チュートリアルとして実装されます。この記事で使用するアドインでは、Project Online アカウントから発行されたプロジェクトのプロジェクト名と ID を読み取って表示し、ドリルダウンして個々のプロジェクトに関連付けられているタスクを取得できます。

実行時に、アドインの一覧は次の図のようになります。

JSOM プロジェクトとタスクの一覧を示すスクリーン

この例の焦点は、Project Onlineとの対話であり、クエリを作成し、サービスからの各要求のコンテキストを設定することです。ユーザーインターフェイス (UI) 要素は、最小限の注意を受けます。代わりに、ソースリストは UI に関するコメントを提供します。

注:

サンプルアドイン (Visual Studio プロジェクト) のソースファイルは、次の.....で https://github.com/OfficeDev/Project-JSOM-List-Projects-Tasks使用できます。ソースファイルは、それぞれを補完する記事の読み取り中に参照として便利なままにします。 Visual Studio プロジェクトビルド内のファイルは、最小限の変更で実行可能であり、Project Online テナントの URL を PWA フォルダーに置き換えます。

背景

Project Onlineは、ポートフォリオ、プログラム、プロジェクトを調整および管理するためのプロジェクトポートフォリオ管理 (PPM) ソリューションとプロジェクト管理オフィス (PMO) ソリューションを企業に提供するOffice 365 サービスです。 Project Onlineは Project デスクトップエディションとは異なるオファリングですが、Project Onlineには、プロジェクトの有効期間を通じてプロジェクトの詳細を維持および追跡するための機能がまだ含まれています。 Project Onlineは SharePoint Online 上に構築されています。

Project Onlineホスト型アドインは、JavaScript と、クライアント側オブジェクトモデル API と対話するリソースファイルで構成されます。ユーザーがアドインにアクセスすると、JavaScript とリソースがブラウザー内でダウンロードされて実行されます。アドインは、データの作成、取得、更新、削除など、Project Onlineを非同期で呼び出してサービスと対話します。

Project Onlineは、アドインから他のテナントに属する情報を保護するためにもう 1 つのアクションを実行します。つまり、Project Onlineは、アドインからの要求と対話する分離されたサイトを作成します。 Project Online ホストでカスタムコードが実行されません。

Project Online アドインの開発セットアップでは、Visual Studio SharePoint アドインプロジェクトの種類が使用されます。アドインは JavaScript で記述され、Project JavaScript オブジェクトモデル (JSOM) を使用してProject Online サービスと対話します。 JSOM は、その機能の多くを SharePoint JSOM から継承します。

注:

アドインは、Office ストアで発行および販売することも、SharePoint 上のプライベートアプリカタログに展開することもできます。詳細については、「 Office アドインを展開して発行する」を参照してください。

この記事で使用されるアドインは、開発者向けのサンプルです。運用環境での使用を目的としたものではありません。主な目的は、Project Onlineのアプリ開発の例を示することです。

前提条件

サポートされている Windows 環境に次の項目を追加します。

.NET Framework 4.0 以降: バージョン 4.0 以降のフレームワークの完全なバージョンは互換性があります。ダウンロードサイトは https://msdn.microsoft.com/vstudio/aa496123.aspx です。
Visual Studio 2013以降:
- Visual Studio 2015 のプロフェッショナルエディションは、すぐに使用できる状態になり、で https://www.visualstudio.com/products/visual-studio-professional-with-msdn-vs.aspx入手できます。
- Visual Studio 2015 のコミュニティエディションは、で https://www.visualstudio.com/products/visual-studio-community-vs.aspx入手できます。このエディションでは、Microsoft Office Developer Tools for Visual Studio を手動でインストールする必要があります。
Microsoft Office Developer Tools for Visual Studio はで https://www.visualstudio.com/features/office-tools-vs.aspx入手できます。
Project Online アカウント: これにより、ホスティングサービスへのアクセスが提供されます。 Project Online アカウントの入手の詳細については、https://products.office.com/Project/project-online-portfolio-management をご覧ください。

アドインユーザーが、Project Online テナント内の一部のプロジェクトにアクセスするための十分な承認を持っていることを確認します。
情報が設定されているホスティングサイト上のプロジェクト 。

注:

標準の.NET Frameworkは、使用する適切なフレームワークです。 ".NET Framework 4 クライアントプロファイル" は使用しないでください。

Visual Studio プロジェクトを設定する

アプリケーションのセットアップは、新しいプロジェクトを作成し、適切なライブラリをリンクし、必要な名前空間を宣言することで構成されます。 Visual Studio では、複数の種類の開発プロジェクトが提供されています。セクションは簡単で非常に基本的です。値は、情報が 1 か所に結合されていることです。

Visual Studio プロジェクトを選択する

アドインに適切な種類のプロジェクトを作成するには、次の手順を実行する必要があります。画面上で検出されたキーワードには、太字の属性があります。

[ファイル] メニューの [ファイル] [新しいプロジェクト] の順に>>選択します。
左側のウィンドウの [インストール済みテンプレート] で、[ C#>Office/SharePoint>Web アドイン] を選択します。
中央のウィンドウの上部にある [.NET Framework 4 以降] を選択します。現在のバージョンは 4.6 です。
中央ウィンドウのアプリケーションの種類から、[ SharePoint アドイン] を選択します。
下部のセクションで、プロジェクトの名前と場所、ソリューション名を指定します。
また、下部のセクションで、[ソリューションのディレクトリを作成] ボックスがオンになっていることを確認します。
[OK] をクリックして、初期プロジェクトを作成します。

Visual Studio ウィザードでは、いくつかのダイアログで、Project Online設定サイト (ダイアログの SharePoint 設定と呼ばれます) についていくつかのフォローアップの質問を行います。質問を次に示します。

アドインのデバッグに使用する SharePoint サイト PWA サイトの URL (など https://contoso.sharepoint.com/sites/pwa) を指定します。
SharePoint アドインをどのようにホストしますか? [X] SharePoint ホスト型を選択します。

ホスティングオプションを含む SharePoint アドインの詳細については、「 SharePoint アドイン」を参照してください。
[次へ] をクリックします。

2 番目の追加ダイアログでは、アドインの SharePoint Online バージョンを指定するように求められます。

アドインのターゲットにする SharePoint の最も古いバージョンは何ですか? [X] S harePoint-Online を選択します。
[完了] をクリックします。

Visual Studio によってプロジェクトが作成され、Project Online サイトにアクセスします。

Project Online サイトでサイドローディングを有効にする

サイドローディングは、アドインProject Onlineテストおよびデバッグするためのメカニズムです。サイドローディングには 2 つのスクリプトが必要です。1 つはProject Online サイトでサイドローディングを有効にし、もう 1 つはアドインのテストとデバッグを完了するとサイドローディングを無効にします。

サイドローディングの設定の詳細については、「開発者以外のサイトコレクションでアプリのサイドローディングを有効にする」を参照してください。

注:

サイドローディングアプリは開発者/テスト機能です。 運用環境での使用を目的としたものではありません。アプリを定期的にサイドロードしたり、アクティブに機能を使用しているよりも長い間アプリサイドローディングを有効にしたりしないでください。

アドインプロジェクトにコンテンツを追加する

プロジェクトを作成し、デバッグメカニズムを設定した後、アプリにコンテンツを追加すると、次のタスクが含まれます。

アプリケーションスコープの設定
JSOM ライブラリのリンク
アドインへの UI 要素の追加
Project Online サービスの初期化と接続
プロジェクトと詳細/プロパティの取得
プロジェクトの表示
プロジェクトのタスクの表示

アドインプロジェクトは、多くのファイルで構成されます。この例では、次のファイルを編集する必要があります。

AppManifest.xml
Default.aspx
App.js
App.css - 省略可能。には、アドイン用に開発されたスタイル定義が含まれています

試用版からサブスクリプションサイトへの移行など、Project Onlineテナントが変更された場合は、[プロパティウィンドウの表示>] コマンドで使用できる [プロパティ] ウィンドウを使用して、サーバー接続やサイト URL など、プロジェクトのプロパティを更新できます。

プロジェクトにファイルを追加することもできます。その場合は、同じグループ (コンテンツ、イメージ、ページ、またはスクリプト) にある Elements.xml ファイルを更新して、新しいファイルを含める必要があります。プロジェクトファイルの詳細については、「アプリマニフェスト構造と SharePoint アドインのパッケージを調べる」を参照してください。

アプリケーションスコープを設定する

アドインには、サービスがクエリ結果の情報を返す前に定義されたスコープレベルまたはアクセス許可レベルが必要です。このアドインでは、Visual Studio プロジェクトに対して次のスコープを使用します。この変更は、[アクセス許可] タブの AppManifest.xml ファイルに対して行われます。

範囲	アクセス許可
複数のプロジェクト (Project Server)	読み取り

アプリケーションスコープを設定した後、ファイルを保存します。それ以外の場合、サービスからデータは返されません。

JSOM ライブラリをリンクする

ランタイム Project Online ライブラリ (PS.js と PS.debug.js) は、Project Onlineによって提供され、常に最新バージョンです。 JSOM を使用する JavaScript アドインは、これらのライブラリのいずれかにリンクする必要があります。リンク定義は、Default.aspx ファイルに追加されます。 PS.js や PS.debug.js を使用するコマンドは、App.js ファイルにあるコードの一部です。

sp.js の "SharePoint:ScriptLink" に続く要素に <asp:Content ContentPlaceHolderID="PlaceHolderAdditionalPageHead" 、PS.js または PS.debug.js 定義に対して次のコマンドを追加します。

<SharePoint:ScriptLink name="PS.js" runat="server" OnDemand="false" LoadAfterUI="true" Localizable="false" />

注:

PS.js または PS.debug.js の OnDemand 属性を false に設定 します。

アドインに UI 要素を追加する

アドインの例は、いくつかのコンポーネントで構成されています。静的要素の説明は、Default.aspx ファイルにあります。すべてのコンポーネントの動的要素の説明とコードは、App.js ファイルにあります。コンポーネントに関するコメントについては、ソースコードの一覧を参照してください。アドインの UI コンポーネントの一覧を次に示します。

タイトル
入門の動詞
テーブルからタスクを削除するボタン
プロジェクト ID と名前、タスク情報を一覧表示するテーブル。
タスクデータをテーブルにインポートするタスクボタン (プロジェクトごとに 1 回複製)。

タイトルやプロジェクトテーブルのヘッダー部分など、ユーザーインターフェイスの詳細については、Default.aspx プロジェクトファイルを参照してください。

ホストシステムを初期化して接続する

App.js ファイルには、JavaScript コードが含まれています。アドインはブラウザーで PS.js を読み込み、initializePage 関数を呼び出します。 InitializePage は、Project Online エンドポイントへのコンテキストを取得し、loadProjects 関数を開始します。

    'use strict';
    SP.SOD.executeOrDelayUntilScriptLoaded(initializePage, "PS.js");
    //Project PWA Context and published projects in PWA
    var projContext;
    var projects;
    function initializePage() {
        //Get the Project context for this web
        projContext = PS.ProjectContext.get_current();
        loadProjects();
    }
    //General CSOM failure event handler
    //Invoked when ExecuteQueryAsync returns unsuccessfully
    function onRequestFailed(sender, args) {
        alert("Failed to execute: " + args.get_message());
        return;
    };

プロジェクトを取得する

loadProjects 関数は、プロジェクト名と ID についてサービスに対してクエリを実行します。

アプリケーションは、プロジェクト名とプロジェクト ID を取得します。プロジェクトに関するその他の情報は使用可能であり、取得するプロパティを明示的に識別するように load メソッドを変更することでアクセスできます。例は、コメントとしてコードで提供されます。

クエリが成功した場合、アドインは displayProjects を呼び出すことによって続行されます。

    //Query CSOM and get the list of projects in PWA
    function loadProjects() {
        projects = projContext.get_projects();
    //Request to server - identifies what to retrieve
        projContext.load(projects, 'Include(Name, Id)');
        //Notice to server to execute query
        projContext.executeQueryAsync(displayProjects, onRequestFailed);
        // Syntax for requesting more fields to pull down from server
        // projContext.load(projects, 'Include(Name, Description, StartDate, 
        // Id, IsCheckedOut)');
    }

プロジェクトを表示する

displayProjects 関数は、テーブル、プロジェクトごとに 1 行、および特定のプロジェクトのタスクを表示するボタンを作成します。

    //Display the projects with names and ids in a table
    function displayProjects() {
        //Current published project and ID
        var p, projId;
        //Project table rows to publish collectively
        var pTable = []; 
        var pEnum = projects.getEnumerator();
        //Build a 3-column table, with one project per row.
        while (pEnum.moveNext()) {
            p = pEnum.get_current();
        
            //Items used in getting information for table rows:
            //Current published project object, and ID and name
            // var project = p;
            // var projId = p.get_id();
            // var projName = p.get_name();
        
            //Continue processing/working with project object as needed.
        }
    }

注:

while ループは、ID プロパティと名前プロパティにアクセスします。これは、同じプロパティにアクセスする関数を呼び出すソースコードプロジェクトとは若干異なります。

プロジェクトのタスクを表示する

タスクはアドインの一部ですが、初期読み込みの一部ではありません。ユーザーがプロジェクトに関連付けられているタスクに関心がある場合は、[タスクの表示] ボタンをクリックすると、btnLoadTasks イベントハンドラーを使用してタスクが一覧に表示されます。

btnLoadTasks イベントハンドラーは、適切なプロジェクト ID を使用して、指定したプロジェクトのタスクをサーバーから要求します。取得されると、btnLoadTasks はタスクリストを渡して displayTasks を表示し、タスクを画面上に表示します。

    //Query CSOM and get the list of tasks for a specific project
    function btnLoadTasks(pid) {
        //Event handler for the "Show tasks" buttons. 
        //
        //The project ID is the sole argument and is used to get the appropriate task 
        //info from the service.
        //The project ID is also the button name, and is used to identify where to place
        //the task information in the table.
        //
        //Project ID to pass to the event handler
        var projId = pid;
        //
        //Get the project reference
        var pProj = projects.getById(projId);
        //
        //Get the tasks collection reference associated with the project.
        var tasks = pProj.get_tasks();
        //
        projContext.load(tasks, 'Include(Id, Name, Start, ScheduledStart, Completion)');
        //
        //If the query succeeds, displayTasks presents the tasks to the user.
        projContext.executeQueryAsync(function () { displayTasks(tasks, projId) }, onRequestFailed);
    }

displayTasks 関数は、指定したプロジェクトに関連付けられているタスクをプロジェクトエントリのすぐ下に表示します。

    //Insert tasks for the specified project immediately underneath the project entry 
    //in the table.
    function displayTasks(tasks, projId) {
        //selected project ID
        var pId = projId;
        //individual task
        var t;
        //Task table rows to publish collectively
        var tTable = [];
        var tEnum = tasks.getEnumerator();
        //Build table one task per row.
        while (tEnum.moveNext()) {
            t = tEnum.get_current();
            //
            //Items used in getting information for table rows:
            //Current task object, and ID and name
            // var task = t;
            // var taskId = t.get_id();
            // var taskName = t.get_name();
            
            //Continue processing/working with task object as needed.
        }
    }

注:

while ループは、タスク ID と名前のプロパティにアクセスします。これは、同じプロパティにアクセスする関数を呼び出すソースコードプロジェクトとは若干異なります。

1 つのプロジェクトのタスクの出力例を次に示します。

プロジェクトタスクの出力を示すスクリーンショットプロジェクトタスク

次の方法で共有

JavaScript オブジェクト モデル (JSOM) を使用したProject Online アドインの開発

背景

前提条件

Visual Studio プロジェクトを設定する

Visual Studio プロジェクトを選択する

Project Online サイトでサイドローディングを有効にする

アドイン プロジェクトにコンテンツを追加する

アプリケーション スコープを設定する

JSOM ライブラリをリンクする

アドインに UI 要素を追加する

ホスト システムを初期化して接続する