SharePoint Framework におけるチーム ベースの開発Team-based development on the SharePoint Framework

SharePoint Framework は、SharePoint カスタマイズをビルドするための新たな開発モデルです。これまでに利用可能な他の SharePoint 開発モデルとは異なり、SharePoint Framework はクライアント側の開発に重点を置き、Gulp や Webpack などの人気のあるオープン ソース ツールを使用してビルドされます。この変更によって生じる大きな利点の 1 つは、SharePoint カスタマイズをあらゆるプラットフォーム上の開発者がビルドできるという点です。SharePoint Framework is a new development model for building SharePoint customizations. Unlike other SharePoint development models available to date, the SharePoint Framework focuses on client-side development and is built on top of popular open source tools such as gulp and webpack. One big benefit of this change is that developers on any platform can build SharePoint customizations.

SharePoint Framework は 1 つの開発モデルで、基礎となるテクノロジの違いに関わりなく、ソリューションのビルドに使用する際に、従来 SharePoint 開発者が使用してきた他の開発モデルと同じ概念が適用されます。SharePoint Framework is a development model, and despite the differences in the underlying technology, the same concepts apply when using it for building solutions as to other development models SharePoint developers used in the past. 開発者は SharePoint Framework ツールチェーンを使用してソリューションのビルドとテストを行い、準備が整うと、SharePoint テナントでさらにテストしてリリースするために展開用ソリューション パッケージを引き渡します。Developers use the SharePoint Framework toolchain to build and test their solutions and once ready, they hand over the solution package to be deployed on the SharePoint tenant for further testing and release.

SharePoint Framework はいくつかの異なるパッケージで構成されています。SharePoint Framework consists of a few different packages. これらのパッケージにはそれぞれ独自のバージョンであり、SharePoint Framework のリリースを構成します。These packages, each in its own specific version, make up a release of the SharePoint Framework. たとえば、SharePoint Framework の一般提供リリースは、次のパッケージ バージョンで構成されています。For example, the General Availability release of the SharePoint Framework consists of the following package versions:

  • @microsoft/sp-client-base v1.0.0@microsoft/sp-client-base v1.0.0
  • @microsoft/sp-core-library v1.0.0@microsoft/sp-core-library v1.0.0
  • @microsoft/sp-webpart-base v1.0.0@microsoft/sp-webpart-base v1.0.0
  • @microsoft/sp-build-web v1.0.0@microsoft/sp-build-web v1.0.0
  • @microsoft/sp-module-interfaces v1.0.0@microsoft/sp-module-interfaces v1.0.0
  • @microsoft/sp-webpart-workbench v1.0.0@microsoft/sp-webpart-workbench v1.0.0

特定のリリースの SharePoint Framework を対象とするプロジェクトの場合、それぞれ適切なバージョンの種々のパッケージすべてを参照しなければなりません。For a project to target a specific release of the SharePoint Framework, it has to reference all the different packages in the correct versions. 新しいプロジェクトをスキャフォールディングする場合、SharePoint Framework Yeoman ジェネレーターによって、対応するリリースの SharePoint Framework から対象パッケージへの必要な参照が自動的に追加されます。When scaffolding new projects, the SharePoint Framework Yeoman generator automatically adds the necessary references to the package from the corresponding release of the SharePoint Framework. ただし、プロジェクトを新しいバージョンの SharePoint Framework にアップグレードする場合、開発者は SharePoint Framework パッケージの適切な更新バージョン番号に特別な注意を払う必要があります。But when upgrading the project to a newer version of the SharePoint Framework, developers have to pay extra attention to correctly update version numbers of the SharePoint Framework packages.

開発環境の準備Preparing the development environment

SharePoint Framework ソリューションをビルドするには、開発者の開発マシンに特定のツールが必要です。他の SharePoint 開発モデルと比べ、SharePoint Framework は制約が少なく、どのようなオペレーティング システムを選択しても最も生産性の高い状態でツールを使用できます。In order to build SharePoint Framework solutions developers need specific tools on the development machines. Comparing to other SharePoint development models, the SharePoint Framework is less restrictive and allows developers to use the tools that make them the most productive going even as far as choosing the operating system.

開発者が開発環境を設定するいくつかの方法があります。それぞれに異なる利点があります。開発者チームが各選択肢についてよく理解しておくことが重要になります。There are a few different ways in which developers can configure their development environment. Each of them has different advantages and it's important that developer teams have a good understanding of the different options.

SharePoint Framework ツールチェーンSharePoint Framework toolchain

SharePoint Framework ソリューションをビルドするには、特定のツールセットを使用する必要があります。次の一覧は、各 SharePoint Framework 開発環境で必要な基本的ツールセットを網羅しています。Building SharePoint Framework solutions requires developers to use a certain set of tools. Following list covers the basic set of tools required on every SharePoint Framework development environment.

Node.jsNode.js

SharePoint Framework では、開発者マシンに Node.js がインストールされている必要があります。Node.js は、プロジェクトのビルドとパッケージ化のためのデザイン時ツール用のランタイムとして使用されます。Node.js は開発者マシンにグローバルにインストールされます。必要な場合には、複数バージョンの Node.js の同時実行に対応するためのソリューションを利用できます。SharePoint Framework requires Node.js to be installed on the developer machine. Node.js is used as the runtime for design-time tools used to build and package the project. Node.js is installed globally on the developer machine and there are solutions available to support running multiple versions of Node.js side-by-side if necessary.

詳細については、Node.js のインストールとサポートされているバージョンを参照してください。For more information, see installing Node.js and the supported versions.

npmnpm

npm は .NET プロジェクトの NuGet に相当します。これにより、SharePoint Framework プロジェクトで使用するパッケージを取得してインストールできます。npm is the equivalent of NuGet in .NET projects: it allows developers to acquire and install packages for use in SharePoint Framework projects. また npm は、SharePoint Framework ツールチェーンをインストールするときにも使用されます。Npm is also used to install the SharePoint Framework toolchain. 通常、開発者は最新バージョンの npm を使用し、開発者マシンにグローバルにインストールします。Typically developers will use the latest version of npm and install it globally on their machine. npm 自体は Node.js パッケージであるため、複数バージョンの Node.js を同時実行すると、それぞれ独自のバージョンの npm がインストールされます。Npm itself is a Node.js package so if you're running multiple versions of Node.js side-by-side each will have its own version of npm installed.

gulpgulp

gulp は .NET プロジェクトの MSBuild に相当し、SharePoint Framework プロジェクトのビルドやパッケージ化などのタスクの実行を担います。gulp は Node.js パッケージとして配布され、通常、npm を使用してグローバルにインストールされます。gulp is the equivalent of MSBuild in .NET project and is responsible for running tasks such as building or packaging a SharePoint Framework project. gulp is distributed as a Node.js package and is typically installed globally using npm.

Yeoman および SharePoint Framework Yeoman ジェネレーターYeoman and SharePoint Framework Yeoman generator

開発者は、Yeoman および SharePoint Framework Yeoman ジェネレーターを使用して新しい SharePoint Framework プロジェクトを作成します。Yeoman とそのジェネレーターはどちらも Node.js パッケージとして配布され、通常、npm を使用してグローバル パッケージとしてインストールされます。グローバル インストールの利点として、開発者が Yeoman とジェネレーターを一度にインストールし、それらを使用して簡単に新しいプロジェクトの作成できるという点があります。Using Yeoman and the SharePoint Framework Yeoman generator developers create new SharePoint Framework projects. Both Yeoman and its generators are distributed as Node.js packages and are typically installed using npm as global packages. The benefit of a global installation is that developers can install Yeoman and the generators once and use them to easily create new projects.

SharePoint Framework Yeoman ジェネレーターは特定の SharePoint Framework バージョンと関連付けられています。ジェネレーターを使用してスキャフォールディングされたプロジェクトは、特定のバージョンの SharePoint Framework パッケージを参照し、生成された Web パーツは対象フレームワークの特定部分を参照します。SharePoint Framework Yeoman ジェネレーターは新しいプロジェクトを作成するためだけでなく、Web パーツを既存のプロジェクトに追加するときにも使用されます。それをグローバルにインストールし、作成済みの既存のプロジェクトに新しい Web パーツを追加すると、新たに作成した Web パーツが、プロジェクトの残りの部分と整合性のない状態になり、ビルド エラーになる可能性もあります。この記事では、この制限を回避できるいくつかの方法について後ほど取り上げます。The SharePoint Framework Yeoman generator is tied to a specific version of the SharePoint Framework. Projects scaffolded using the generator, reference the specific versions of the SharePoint Framework packages and the generated web parts reference the specific pieces of the framework. The SharePoint Framework Yeoman generator is used for creating new projects but also for adding web parts to existing projects. If you install it globally and would have to add a new web part to an existing project created in the past, the newly created web part might be inconsistent with the rest of the project which might even lead to build errors. There are a number of ways in which you can work around this limitation which this article discusses later on.

TypeScriptTypeScript

SharePoint Framework は TypeScript を使用して、より優れたコードを記述したり、開発時にエラーをキャッチしたりして開発者の生産性を高めます。SharePoint Framework プロジェクトには独自のバージョンの TypeScript が付属しており、ビルド プロセスで使用されます。開発者が別個にインストールする必要はありません。SharePoint Framework uses TypeScript to help developers be more productive by writing better code and catching errors already during development. SharePoint Framework projects ship with their own version of TypeScript which is used in the build process and which doesn't require developers to install it separately.

SharePoint Framework 開発環境のビルドBuilding a SharePoint Framework development environment

以前は、SharePoint 開発者は仮想マシンを開発環境として使用することが一般的でした。仮想マシンを使用すると、ビルドするソリューションを、特定の組織が使用する環境で確実に動作させることができました。仮想マシンでは、開発者は SharePoint をインストールして、特定の組織が使用する運用環境と同じレベルに合わせて調整しました。場合によっては、追加ソフトウェアをインストールして、対象ソリューションの動作が可能な限り対象環境と類似するようにしました。この方法では、異なる環境で生じるエラーを早期にキャッチできるものの、複雑さや各種環境を管理しなければならないという欠点もありました。In the past SharePoint developers typically used virtual machines as their development environments. Virtual machines allowed them to ensure that the solution they were building would work on the environment used by that particular organization. In their virtual machines developers would install SharePoint and patch it to the same level as the production environment used by the particular organization. In some cases they would install additional software to match the target environment where the solution would run as closely as possible. This approach allowed developers to catch any errors caused by the difference in environments earlier at the cost of complexity and managing the different environments.

クラウド用ソリューションの開発に移行しても、部分的にしか問題は解決しませんでした。開発者は SharePoint ファームを開発マシンで実行する必要はなくなりましたが、ソリューションがホストされる方法や、SharePoint Online と通信する方法について考慮する必要が生じました。Moving to developing solutions for the cloud solved these issues only partly. While developers no longer needed to run a SharePoint Farm on their development machines, they had to take into account how their solution would be hosted and how it would communicate with SharePoint Online.

SharePoint Framework はクライアント側の開発に焦点を当てているため、SharePoint を開発マシンにインストールする必要はありません。わずかな例外を除き、フレームワークと他のパッケージに対するすべての依存関係はプロジェクトで指定され、プロジェクト フォルダーに入れられます。SharePoint Framework はもともとクラウドで作成され、頻繁に更新されるので、開発者は使用している SharePoint Framework プロジェクトに対応する最新バージョンのツールチェーンを使用するようにしなければなりません。As SharePoint Framework focuses on client-side development it no longer requires SharePoint to be installed on the development machines. With a few exceptions, all dependencies to the framework and other packages are specified in the project and contained in the project folder. As the SharePoint Framework has its origins in the cloud and evolves frequently, developers must ensure that they are using the correct version of the toolchain corresponding to their SharePoint Framework project.

共有または個人用の開発環境Shared or a personal development environment

SharePoint カスタマイズは、ページに直接追加される簡単なスクリプトから、ソリューション パッケージとして展開される高度なソリューションまで、幅広い範囲に及びます。SharePoint Framework は、SharePoint カスタマイズの構造化されて繰り返し使用できる開発モデルを対象とする開発モデルです。SharePoint Framework ソリューションをビルドするとき、チームの各開発者は独自の開発環境を使用し、プロジェクトのソース コードを、ソース管理システムを介してチームの他の開発者と共有します。この方法を使用すると、複数の開発者が同時に同じプロジェクトで作業し、それぞれの生産性に影響を及ぼすことなくソリューションをテストできます。SharePoint customizations range from simple scripts being added directly to the page to sophisticated solutions deployed as solution packages. SharePoint Framework is a development model targeting the structured and repeatable deployment model of SharePoint customizations. When building SharePoint Framework solutions each developer on the team uses his own development environment and shares the source code of the project with other developers on the team through a source control system. This way developers can work on the same project simultaneously and test their solution without affecting each others productivity.

これまでは、多くの組織において SharePoint 開発者たちに高性能の開発マシンを提供することは課題となり、場合によっては複数の開発者が生産性を犠牲にしても同じマシンを共有する必要がありました。SharePoint Framework を使用すると、開発者は市場に出回っている標準的な開発者マシンを使用して SharePoint カスタマイズをビルドできます。In the past it was challenging for many organizations to justify providing SharePoint developers with very powerful development machines and in some cases multiple developers had to share the same machine at the cost of productivity. With SharePoint Framework developers can use market-standard developer machines to build SharePoint customizations.

ホスト上での開発Developing on the host

SharePoint Framework プロジェクトの開発環境をセットアップする最も簡単な選択肢となるのは、多くの場合、ホスト マシンにツールすべてを直接インストールするという方法です。チームが SharePoint Framework プロジェクトでのみ作業している場合、Node.js を各自のマシンにインストールできます。他の Node.js プロジェクトでも作業している場合には、nvm などのサード パーティ製ソリューションを使用して複数バージョンの Node.js を同時実行できます。Probably the easiest option to setup a development environment for SharePoint Framework projects is to install all the tools directly on the host machine. If your team is working only on SharePoint Framework projects, then they can install Node.js on their machines. If they work on other Node.js projects as well then they could use third party solutions such as nvm to run multiple versions of Node.js side-by-side.

SharePoint Framework ツールチェーンで必要なツールに続いて、開発者は Yeoman と SharePoint Framework Yeoman ジェネレーターをインストールします。Following the tools required by the SharePoint Framework toolchain, developers would install Yeoman and the SharePoint Framework Yeoman generator. 通常、これら両方のツールはグローバルにインストールされます。Typically both these tools are installed globally. ただし、SharePoint Framework Yeoman ジェネレーターが特定のバージョンの SharePoint Framework に関連付けられていて、開発者が異なるバージョンで作成されたプロジェクトで作業する必要がある場合、その時点で作業している特定のプロジェクトに固有のジェネレーター バージョンをアンインストールしてからインストールする必要があります。Given however, that the SharePoint Framework Yeoman generator is tied to a specific version of the SharePoint Framework and developers might need to work with projects created using a different version, they would have to uninstall and install the version of the generator specific for the particular project they are working on at the moment. より実際的な方法は、対象プロジェクトで Yeoman をグローバルに、SharePoint Framework Yeoman ジェネレーターをローカルにインストールすることです。A more viable approach would be to install Yeoman globally but the SharePoint Framework Yeoman generator locally in the given project. その場合には若干のオーバーヘッドが生じますが、開発者は、今後、対象プロジェクトに新しい要素を追加しなければならない場合に、プロジェクトの残りの部分と互換性を確保できます。While it introduces some overhead, it helps developers ensure that should they need to add new elements to the project in the future they would be compatible with the rest of the project.

ホストで開発する大きな利点としては、開発者が自身のマシンで一度ユーザー設定を行うと、その設定をすべてのプロジェクトで使用できるという点があります。また、ホストでソフトウェアを実行すると、中間に仮想化レイヤーを使用せずに CPU、メモリ、ディスク入出力に直接アクセスできるので、同じソフトウェアを仮想化して実行するよりもパフォーマンスが向上します。Big benefit of developing on the host is that developers can configure their machine to their preferences once and use it across all projects. Also, as the software executes on the host, it has direct access to the CPU, memory and disk I/O without a virtualization layer in between which leads to a better performance than when running the same software virtualized.

仮想マシンにおける開発Developing in a virtual machine

以前は SharePoint 開発者が SharePoint ソリューションをビルドするための主要な開発環境として最もよく使用するのは仮想マシンでした。仮想マシンを使用すると、開発者は各種プロジェクトの異なる要件に適応できました。In the past the most common approach amongst SharePoint developers was to use virtual machines as their primary development environment for building SharePoint solutions. Using virtual machines developers could accommodate the different requirements for the different projects.

SharePoint Framework でソリューションをビルドすると、これまで SharePoint ソリューションをビルドする際に使用していたのと同じ利点を活用できます。仮想マシンを使用すると、開発ソフトウェアをホスト オペレーティング システム (特に大規模な組織で一般的な要件) から切り離すことができます。プロジェクトごとに分離した仮想マシンを作成すると、プロジェクトで使用するツールチェーンに関して、今後、他の特定のプロジェクトを選択する必要が生じても、プロジェクトとの互換性を確保できます。When building solutions on the SharePoint Framework organizations can use the same benefits as they used with building SharePoint solutions in the past. Using virtual machines they can isolate the development software from the host operating system which is a common requirement particularly in large organizations. By creating a separate virtual machine for each project developers can ensure that the toolchain they use is compatible with the project even if they need to pick up the particular project in the future.

仮想マシンの使用には、欠点がないわけではありません。仮想マシンは大規模になり、生産性に関して十分なパフォーマンスを確保して実行するにはとても強力なコンピューターを使用する必要があります。また、かなり長期間にわたり、オペレーティング システムを最新の状態に維持し、必要なセキュリティ更新すべてを確実に実行するようにしなければなりません。仮想マシンで作業する開発者は、自分の設定用に標準の仮想マシンを構成するために新たなプロジェクトの開始時にいくらかの時間を費やすか、または生産性を犠牲にして標準のセットアップで妥協する必要があります。仮想マシンはオペレーティング システム全体とそのすべてのコンポーネントを使用して実行するため、チームのすべての開発者が使用する仮想マシンすべてで整合性を維持するのはとても難しいことです。SharePoint Framework ソリューションをビルドするために仮想マシンを使用すると、他のタイプの開発環境に比べて、コストと時間の両面において高価になります。Using virtual machines is not without drawbacks. Virtual machines are big and require developers to use computers powerful enough to run them with acceptable performance to be productive. Additionally, particularly over longer periods of time, developers have to keep the operating system up-to-date and ensure they run all the necessary security updates. As developers work in a virtual machine they either have to spend some time at the beginning of a new project to configure the standard virtual machine to their preferences or have to give in to the standard setup at the cost of their productivity. Because virtual machines run a complete operating system with all its components it's much harder to ensure that all virtual machines used by all developers on the team are consistent. Comparing to other types of development environments, using virtual machines for building SharePoint Framework solutions is expensive both from the cost and time point of view.

Docker を使用した開発Developing using Docker

ホスト上での開発と仮想マシンにおける開発の中間的位置にあるのが、Docker を使用する方法です。Docker は、仮想マシンに似たソフトウェア仮想化テクノロジですが、いくつかの大きな違いがあります。仮想マシンの場合に比べて Docker イメージを使用する最も重要な利点は、Docker イメージは、作成、維持、配布が簡単で、同時に軽量であり (仮想マシンで必要なディスク容量が数十 GB 単位であるのに対し、必要となるのは数百 MB 単位です)、既にホスト マシンにインストールおよび構成されているツールと設定を開発者が利用できる点にあります。An interesting middle ground between developing on the host and in a virtual machine is using Docker. Docker is a software virtualization technology similar to virtual machines with a few big differences. The most important benefits of using Docker images over virtual machines are that Docker images are easier to create, maintain and distribute, they are more lightweight (few hundred MBs comparing to tens of GBs disk space required for virtual machines) and they allow developers to use the tools and preferences they already have installed and configured on their host machine.

仮想マシン同様、Docker コンテナーはオペレーティング システム (最も一般的には Linux ベース) の仮想化インスタンスを実行します。コンテナーを作成するために使用される、イメージ内にインストールされているソフトウェアすべては、そのコンテナー内で独立した状態で実行され、対象コンテナーと明示的に共有されるホスト ファイル システム部分にのみアクセスします。Docker コンテナー内部のファイル システムに対するすべての変更はコンテナーが閉じると破棄されるので、開発者はホストのフォルダーを共有してソース コードを格納します。Similarly to virtual machines, Docker containers run a virtualized instance of an operating system (most commonly based on Linux). All software installed in the image used to create the container runs isolated inside that container and has only access to the portion of the host file system explicitly shared with the container. As all changes to the filesystem inside a Docker container are discarded once the container is closed, developers share folders from their host to store the source code.

SharePoint Framework ソリューションをビルドするための Docker の使用法の詳細を確認してください。Read more about using Docker for building SharePoint Framework solutions.

SharePoint Framework プロジェクトにおける開発ワークフローDevelopment workflow in SharePoint Framework projects

SharePoint Framework はオープン ソース ツールチェーンに基づいていて、同じスタック上にビルドされている他のプロジェクトの一般的な開発ワークフローに従います。一般的な SharePoint Framework プロジェクトで、そのワークフローがどのようになるかを、以下に説明します。SharePoint Framework is based on open source toolchain and follows the general development workflow present in other projects built on the same stack. Following is a description of how that workflow looks like in a typical SharePoint Framework project.

新しい SharePoint Framework プロジェクトの作成Create new SharePoint Framework project

SharePoint Framework を使用して SharePoint カスタマイズをビルドする場合、新しい SharePoint Framework プロジェクトをスキャフォールディングするのが最初のステップです。When building SharePoint customizations using the SharePoint Framework the first step is to scaffold new SharePoint Framework project. これは、SharePoint Framework Yeoman ジェネレーターを使用して実行します。This is done using the SharePoint Framework Yeoman generator. ジェネレーターによって、プロジェクトの名前や場所に関するいくつかの質問に対する答えを求めるダイアログが表示されます。The generator will prompt you to answer a few questions regarding the name of the project or its location. また、最初の Web パーツまたは拡張情報を作成することもできます。It will also allow you to create the first web part or extension. コンポーネントごとに別の JavaScript フレームワークを自由に選択できますが、通常は SharePoint Framework プロジェクトごとに 1 つのフレームワークを使用することをお勧めします。Although you are free to choose a different JavaScript framework for each of your components, the general recommendation is to use a single framework per SharePoint Framework project.

依存関係バージョンのロックLock dependencies version

SharePoint Framework Yeoman ジェネレーターによってスキャフォールディングされた新たな SharePoint Framework プロジェクトは、正しく実行するために必要な SharePoint Framework パッケージ、および他のパッケージに関して依存関係があります。Web パーツをビルドするときに、Angular や jQuery などの他の依存関係を含めたい場合があります。SharePoint Framework プロジェクトでは、依存関係は npm を使用してインストールされます。各依存関係は、特定のバージョンの Node.js パッケージです。既定では、依存関係はバージョン範囲によって参照されます。バージョン範囲を開発者が使用すると、依存関係を最新の状態に簡単に維持できます。この方法を用いると、同一のプロジェクトに関して 2 つの特定時点の依存関係が復元されて異なる結果が生じ、プロジェクトが破損することもあります。A new SharePoint Framework project scaffolded by the SharePoint Framework Yeoman generator has dependencies on the SharePoint Framework packages as well as other packages required for it to run correctly. As you build your web parts you might want to include additional dependencies such as Angular or jQuery. In SharePoint Framework projects dependencies are installed using npm. Each dependency is a Node.js package with a specific version. By default dependencies are referenced using a version range which is meant to help developers keep their dependencies up-to-date more easily. A consequence of this approach is that restoring dependencies for the same project at two points in time might give different results which could even lead to breaking the project.

オープン ソース ツールチェーンでビルドされたプロジェクトの途中で依存関係が変更されるというリスクを回避するための一般的な解決策は、すべての依存関係のバージョンをロックするという方法です。プロジェクトに依存関係を追加するときに、開発者は、npm install コマンドに --save-exact 引数を指定して呼び出すことによって、バージョン範囲ではなく、特定のバージョンの依存関係をインストールできます。ただし、これは特定のパッケージの子依存関係には影響を及ぼしません。プロジェクト内のすべてのバージョンの依存関係とその子を効率的にロックするには、npm shrinkwrap コマンドを使用できます。このコマンドを実行すると、実行時のすべての依存関係とそのバージョンの一覧が生成され、ソース管理に含める必要がある npm-shrinkwrap.json ファイルに記録されます。依存関係を復元すると、npm では、特定のバージョン範囲の最新バージョンではなく、このファイルに基づいて正確なバージョンを使用します。A common solution to avoid the risk of dependencies changing during the project, in projects built on the open source toolchain, is to lock the version of all dependencies. When adding a dependency to the project developers can choose to install the dependency with a specific version rather than a version range by calling the npm install command with the --save-exact argument. This however doesn't affect the child dependencies of the particular package. To effectively lock the version of all dependencies and their children in the project, developers can use the npm shrinkwrap command. Once executed, it will generate a list of all dependencies and their versions at the moment of execution and record it in the npm-shrinkwrap.json file which should be included in the source control. When restoring dependencies npm will use the exact versions from this file rather than the latest version satisfying the particular version range.

注意

package.json ファイル内の依存関係一覧に含まれていない、またはいずれのパッケージの依存関係でもないパッケージが node_modules フォルダーにインストールされている場合、npm-shrinkwrap.json ファイルを生成するとエラーが表示される可能性があります。If you have any packages installed in the node_modules folder that are not listed as dependencies in the package.json file or are not a dependency of one of the packages, you will likely see an error when generating the npm-shrinkwrap.json file. その場合、エラーの原因となっているパッケージを確認し、対象パッケージを package.json に追加するか、node_modules フォルダーから削除できます。または、node_modules フォルダーごと削除してから、すべての依存関係を復元し、shrinkwrap ファイルを生成できます。In this case, you can either see which packages are causing the error and add them to the package.json, or remove them from the node_modules folder, or you can delete the node_modules folder altogether, restore all dependencies and generate the shrinkwrap file then.

ソース管理へのプロジェクトの追加Add the project to source control

チームの他のメンバーが同じプロジェクトで作業できるようにするには、チームが使用しているソース管理システムに対象プロジェクトを追加します。チームが使用するシステムによって、詳細なステップは異なります。To allow the rest of the team to work on the same project add it to the source control system that your team is using. The exact steps will differ depending on the system used by your team.

SharePoint Framework プロジェクトは、.gitignore ファイルを使用してスキャフォールディングされます。このファイルには、ソース管理から除外する必要があるファイルが記述されています。Git 以外のソース管理システム (Team Foundation System リポジトリを使用した Visual Studio Team System など) をチームで使用している場合、ソース管理にプロジェクトの適切なファイルを含めていることを確認しなければなりません。また、依存関係と、ビルド プロセスで自動生成されたファイルを除外すると、チームの作業効率が上がります。SharePoint Framework projects are scaffolded with the .gitignore file which describes which files should be excluded from the source control. If your team is using a source control system other than Git (such as Visual Studio Team System with Team Foundation System repositories), you should ensure that you are including correct files from the project in the source control. Also excluding the dependencies and autogenerated files during the build process allows you to ensure that your team will work efficiently.

開発者がソース管理に含めないように特に注意しなければならない 1 つの場所は、node_modules フォルダーです。One location developers should particularly pay attention not to include in the source control is the node_modules folder. このフォルダーには、プロジェクトが依存するパッケージと、npm install コマンドを使用して依存関係を復元するときに自動的にインストールされるパッケージが入っています。This folder contains packages on which the project depends and which are automatically installed when restoring dependencies using the npm install command. 一部のパッケージは、バイナリにコンパイルされます。このコンパイル プロセスはオペレーティング システムに依存しています。Some packages compile to binaries where the compilation process depends on the operating system. チームが異なるオペレーティング システムで作業している場合に、node_modules フォルダーをソース管理に含めると、一部のチーム メンバーのビルド内容が破損する可能性があります。If the team is working on different operating system then including the node_modules folder in the source control will likely break the build for some team members.

ソース管理からのプロジェクトの取得Get the project from source control

ソース管理から初めてプロジェクトを取得するときに、プロジェクトのソース コードは取得できますが、プロジェクトのビルドに必要な SharePoint Framework ライブラリはまったく取得できません。.NET プロジェクトで NuGet パッケージを使用して作業する場合と同様、最初に依存関係を復元する必要があります。SharePoint Framework プロジェクトでは、Node.js の上にビルドされる他のすべてのプロジェクト同様、コマンドラインで npm install を実行します。npm は package.json ファイルからの情報と npm-shrinkwrap.json ファイルからの情報を組み合わせて使用し、すべてのパッケージをインストールします。The first time you will get the project from source control, you will get the project's source code but none of the SharePoint Framework libraries required to build the project. Similarly to when working with .NET projects and using NuGet packages, you have to restore the dependencies first. In SharePoint Framework projects, similarly to all other projects built on top of Node.js, you do that by executing npm install in the command line. npm will use the information from the package.json file combined with the information from the npm-shrinkwrap.json file and install all packages.

注意

通常、npm install コマンドを使用して依存関係を復元するには、registry.npmjs.org からパッケージをダウンロードするためにインターネット接続が必要になります。ネットワーク接続で問題が発生する場合、または npmjs レジストリを利用できない場合には、ビルドが失敗します。Typically restoring dependencies using the npm install command requires internet connectivity as packages are downloaded from registry.npmjs.org. If you experience network connectivity issues or the npmjs registry is unavailable your build will fail. この制限を緩和する方法がいくつかあります。There are a number of ways to mitigate this limitation. 1 つの方法は、shrinkpack を使用してすべての依存関係の tarball をダウンロードし、ソース管理に格納することです。One of them is using shrinkpack to download tarballs of all dependencies and have them stored in the source control. Shrinkpack は npm-shrinkwrap.json ファイルを自動的に更新して、プロジェクトの依存関係のオフライン インストールを可能にするローカル tarball を使用します。Shrinkpack automatically updates the npm-shrinkwrap.json file to use the local tarballs allowing for offline installation of the project's dependencies.

一部のパッケージは、インストール プロセス中にバイナリにコンパイルされます。このコンパイル プロセスは、アーキテクチャとオペレーティング システムに固有です。たとえば、Linux を実行する Docker コンテナーで依存関係を復元し、Windows ホスト上でプロジェクトをビルドしようとすると、バイナリをビルドして実行するために使用する環境の種類が異なることを報告するエラーを受け取ります。Some of the packages are compiled into binaries during the installation process. This compilation process is specific to the architecture and operating system. If you would for example restore dependencies in a Docker container running Linux and would then try to build the project on your Windows host you would get an error reporting the mismatch in the environment type used to build and run the binaries.

チームでソリューションを開発する過程で、新しい依存関係または更新された依存関係がプロジェクトに追加されることがあります。ソース管理からプロジェクトを最後に取得した後に package.json ファイルが変更された場合、コマンドラインで npm install を実行して、不足している依存関係をインストールする必要があります。package.json ファイルが変更されたかどうか不確かな場合、コマンドラインで npm install を実行することによって、プロジェクトに悪影響を与えることなく、最新の依存関係があることを確認できます。As your team develops the solution, new or updated dependencies might be added to the project. If the package.json file has changed since you last got the project from the source control, you will have to run npm install in the command line to install the missing dependencies. If you are unsure if the package.json file has changed, you can run npm install in the command line just to be sure that you have the latest dependencies, without any harm to the project.

プロジェクトへのパッケージの追加Add packages to your project

特定のタスクを実行するために既存のパッケージを使用することによって、生産性を高めることができます。npmjs.com は、プロジェクトで使用できるパッケージの公開レジストリです。Using existing packages to accomplish specific tasks allows you to be more productive. npmjs.com is a public registry of packages that you can use in your project.

重要

パッケージを npmjs.com に公開する前に行う公式な検証プロセスはないため、特定のパッケージが使用可能かどうかをコンテンツとライセンスの両面から注意深く調べる必要があります。Since there is no formal verification process before a package is published to npmjs.com, you should carefully examine if you can use the particular package both from the contents and license point of view.

パッケージを SharePoint Framework プロジェクトに追加するには、コマンドラインで npm install <package> --save コマンドまたは npm install <package> --save-dev コマンドを実行します (例: npm install angular --save)。--save 引数または --save-dev 引数を使用すると、パッケージは package.json ファイルに確実に追加され、チームの他の開発者も同様に、依存関係を復元するときにそれを取得します。このようにしないと、自分以外のマシンでプロジェクトをビルドすると失敗します。Angular や jQuery など、ランタイムで、ソリューションが必要とするパッケージを追加する場合、--save 引数を使用する必要があります。追加の gulp タスクなどの、ビルド プロセスで必要なパッケージは、--save-dev 引数を付けてインストールしなければなりません。To add a package to your SharePoint Framework project execute the npm install <package> --save or npm install <package> --save-dev command in the command line, eg. npm install angular --save. Using the --save or --save-dev argument ensures that the package is added to the package.json file and other developers on your team will get it as well when restoring dependencies. Without it building the project on a machine other than your own will fail. When adding packages that are required by your solution on runtime, such as Angular or jQuery, you should use the --save argument. Packages that are required in the build process, such as additional gulp tasks, should be installed with the --save-dev argument.

パッケージをインストールするときに、バージョンを指定しないと、npm はパッケージ レジストリ (既定では npmjs.com) で使用可能な最新バージョンをインストールします。これは通常、使用したいバージョンです。パッケージのバージョンを開発者が指定する必要があるケースの 1 つは、npm-shrinkwrap.json を使用していて、既存のパッケージを新しいバージョンにアップグレードする場合です。既定では、npm は npm-shrinkwrap.json ファイルにリストされているバージョンをインストールします。npm install コマンド (npm install angular@1.5.9 --save など) でバージョン番号を指定すると、対象パッケージがインストールされ、npm-shrinkwrap.json ファイルのバージョン番号が更新されます。When installing a package, if you don't specify a version, npm will install the latest version available in the package registry (npmjs.com by default), which usually is the version that you will want to use. One specific case when you have to specify the version of the package is when you're using npm-shrinkwrap.json and want to upgrade an existing package to a newer version. By default npm will install the version listed in the npm-shrinkwrap.json file. Specifying the version number in the npm install command, like npm install angular@1.5.9 --save, will install that package and update the version number in the npm-shrinkwrap.json file.

内部パッケージの操作Working with internal packages

チームがクライアント側ソリューションを開発する過程で、プロジェクト全体で再利用するコードの共通ライブラリをビルドする可能性は高いでしょう。多くの場合、そのようなライブラリには、運用環境に展開されるバンドル以外に、組織外で公に共有されることのない専用コードも含まれます。SharePoint Framework プロジェクトを扱うときに、チームがプロジェクトで内部ライブラリを活用するための方法がいくつかあります。As your team is developing client-side solutions, you will very likely build common libraries of code that you would like to reuse across all your project. In many cases such libraries contain proprietary code not shared publicly outside the organization, beyond the bundles deployed to production. When working with SharePoint Framework projects, there are a number of ways your team can leverage your internal libraries in their projects.

プライベート パッケージ レジストリのホスティングHosting private package registry

以前は、.NET ソリューションをビルドした多くの組織で NuGet プライベート リポジトリをホスティングし、内部パッケージ用に NuGet パッケージ管理システムを活用してきました。SharePoint Framework はパッケージ管理に npm を使用するため、組織は同様に、内部パッケージにプライベート レジストリを使用できます。内部で開発されたパッケージはプライベート レジストリに公開され、組織内のすべてのプロジェクトで使用されます。In the past, many organizations building .NET solutions hosted private NuGet repositories to benefit of the NuGet package management system for their internal packages. As SharePoint Framework uses npm for package management, organizations could similarly use a private registry for their internal packages. Packages developed internally would be published to the private registry and be used in all projects within the organization.

プライベート パッケージ レジストリを使用するとき、組織は、クラウドでホスティングされる各種のオファリングの中から選択するか、または組織独自のインフラストラクチャで独自のレジストリをホスティングすることができます。When using private package registries organizations can choose between different offerings hosted in the cloud or they can host their own registry on their own infrastructure.

プライベート パッケージ レジストリを使用すると、各種のパッケージで使用される共通コードの管理に集中できます。組織は、共有コード ベースに対する変更についての別個の管理計画を定義すると、高品質のコード ライブラリを確保し、コード ライブラリによるプロジェクトの処理速度の低下という重荷を負わせることなく、すべての開発者に意図どおりの利点を提供できます。Using a private package registry allows organizations to centrally manage common code used across the different projects. By defining a separate governance plan around contributing changes to the shared code base, organizations can ensure that the code library is of high quality and that it offers all developers benefits as intended rather than being a burden slowing projects down.

Visual Studio Team Services または Team Foundation Server を使用する組織では、簡単に VSTS/TFS で直接、プライベート npm レジストリを作成できます。Organizations using Visual Studio Team Services or the Team Foundation Server, can conveniently create a private npm registry directly in VSTS/TFS. 他のソース管理システムを使用する組織では、他のソリューションを使用してパッケージをホストできます。Organizations using other source control systems, can use other solutions for hosting their packages. クラウドでホスティングされる人気のあるプライベート レジストリは npm Enterprise です。A popular private registry hosted in the cloud is npm Enterprise. 組織自体でレジストリをホスティングすることに関心がある場合、Sinopia またはその枝分かれである Verdaccio、あるいは Nexus などの多数あるオープン ソース実装から選択できます。Organizations that are interested in hosting their registry themselves can choose from a number of open source implementations such as Sinopia or its fork Verdaccio or Nexus.

注意

プライベート パッケージ レジストリをホスティングするためのエンジンが異なると、開発ステージも異なるため、ご使用の要件を満たすエンジンについて、機能、ライセンス、サポートのそれぞれの面から注意深く評価する必要があります。Different engines for hosting private package registries are in different development stages and you should carefully evaluate that the particular engine meets your requirements, both from the functionality, license and support point of view.

プライベート パッケージ レジストリのインストールと管理を簡単にするため、ほとんどのエンジンにはすぐに使用できる Docker イメージが備わっています。To simplify the installation and management of a private package registry, most engines offer ready-to-use Docker images.

プライベート レジストリを使用する以外の方法は、パッケージのリンクを設定することです。レジストリをセットアップする必要はありませんが、すべての開発者マシンとビルド サーバーを慎重に調整しなければなりません。An alternative to using a private registry is linking packages. While it doesn't involve setting up a registry, it requires careful coordination on all developer machines and the build server.

最初に、チームのすべての開発者がそれぞれの開発マシンで共有パッケージのコピーを入手する必要があります。各開発者はコマンドラインで、作業ディレクトリをいずれかの共有パッケージに変更してから、npm link コマンドを実行します。このコマンドは、特定のパッケージを、特定の開発マシンでグローバル パッケージとして登録します。次に、各開発者は、共有パッケージを使用するプロジェクトのディレクトリに作業ディレクトリを変更します。その後、コマンドラインで npm install <shared_package> --save コマンドを実行して、他のパッケージと同様の方法で対象パッケージをインストールします。共有パッケージはグローバルにインストールされるので、npm は、パッケージのインストール ソースとして対象バージョンを使用します。この時点で、プロジェクトの観点からは、パッケージは他のパブリック パッケージと同様にインストールされます。開発者は、パッケージをプロジェクトにバンドルする方法を選択できます。First, every developer on the team must get a copy of the shared package on their development machine. In the command line they have to change the working directory to the one of the shared package and then they must execute the npm link command. This command registers the particular package as a global package on that particular development machine. Next, developers have to change the working directory to the directory of the project in which they would like to use the shared package. Then they install the package the same way they would install any other package by executing the npm install <shared_package> --save command in the command line. As the shared package is installed globally, npm will use that version as the source to install the package from. At this point, from the project point of view, the package is installed just like any other public package and developers can choose how they want to bundle the package with the project.

パッケージのリンク設定は、すべての開発者マシンとビルド サーバーで実行する必要があります。共有パッケージを npm link コマンドを使用してリンク設定しないと、プロジェクト依存関係の復元が失敗し、ビルドできません。Linking the package must be executed on all development machines as well as on the build server. If the shared package isn't linked using the npm link command, restoring project dependencies will fail breaking the build.

リンク設定されたパッケージの参照は、共有パッケージとプロジェクトを同時に開発する場合に、プロジェクトの早い段階で特に役立ちます。リンク設定されているおかげで、プロジェクトで最新のコードを使用するためにパッケージの新しいバージョンをレジストリに公開する必要がありません。留意すべきリスクの 1 つとして、ローカルに変更を加え、ソース管理にまだコミットしていない共有ライブラリのバージョンを開発者が参照すると、他のチーム メンバーのビルドが壊れることになります。Referencing linked packages is particularly helpful early in the project when you are developing the shared package and the project at the same time. Thanks to linking you don't need to publish new version of the package to the registry in order to use the latest code in your project. A risk worth keeping in mind is that if developers would reference a version of the shared library that they changed locally and which they haven't committed to the source control, it would break the build for the rest of the team.

プライベート パッケージ レジストリとパッケージのリンク設定の組み合わせCombining private package registry and linking packages

パッケージのリンク設定は、プライベート レジストリと組み合わせて使用できます。たとえば、開発者たちがリンク設定されたパッケージを参照し、ビルド サーバーによってプライベート レジストリから共有ライブラリをプルするという方法で作業できます。プロジェクト側からすると、何も変わっていないように見えます。package.json ファイルのパッケージ参照は、リンクされたパッケージとプライベート レジストリのどちらからも解決できます。チームで念頭に置いておくべき唯一の点は、ビルドを実行する前に、共有ライブラリに対する最新の変更内容をプライベート レジストリに公開するということです。Linking packages can be combined with a private registry. You could for example work in a way where developers reference a linked package and the build server pulls the shared library from a private registry. From the project perspective nothing changes: the package reference in the package.json file can be resolved both from a linked package as well as from a private registry. The only thing your team has to keep in mind is to publish the latest changes to the shared library to the private registry before executing the build.

共有ライブラリのコードは時経つうちに安定し、特定のプロジェクトの必要に応じて変更を加える必要は減っていくので、多くの場合に開発者は公開されたパッケージを変更するのではなく、プライベート レジストリから参照するだけで済みます。As the code of the shared library stabilizes over time and fewer changes are needed to accommodate the needs of the specific projects, developers would be more likely to just reference the published package from the private registry rather than changing it.

コードの整合性と品質の確保Ensuring code consistency and quality

ソフトウェア開発チームでよく課題となるのは、プロジェクトの整合性と高品質を維持する点です。開発者ごとにコーディング スタイルと好みが異なります。どのチームにも、熟練した開発者と、特定のドメインで経験の少ない開発者が存在します。また、多くの組織や業種にはソフトウェアが準拠する必要がある特定の規制があります。これらの課題すべてによって、開発者が計画どおりに物事を進めることが難しくなります。特に、期日が近づくと、開発者は品質を犠牲にして物事を進める傾向があります。そのようにすると、長期的観点からは期日に間に合わないよりも害が大きくなります。Software development teams often struggle with maintaining consistency and high quality of their projects. Different developers have different coding styles and preferences. In every team there are more skilled individuals as well as developers who are less experienced in the particular domain. Also, many organizations or verticals have specific regulations with which the software must comply. All these challenges make it harder for developers to stay on track. Particularly when the deadline is nearby developers tend to get things done at the cost of the quality which in the long run is more harmful than not meeting the deadline.

チームにおける JavaScript ライブラリの選択とコーディング標準の使用Choose JavaScript library for your team and use coding standards

チームがこれまでに SharePoint カスタマイズをビルドした経験がある場合、カスタマイズのビルド方法やプロジェクトで使用するツールとライブラリを定めたコーディング標準が存在する可能性があります。コーディング標準を使用すると、コードから各開発者の個人的な嗜好を排除し、チームの他のメンバーが簡単に採用できるようになります。また、コーディング標準は長年にわたって積み上げられてきたチームの経験を反映するため、カスタマイズのビルド効率と品質を向上できます。If your team has been building SharePoint customizations in the past, you very likely have coding standards that describe how you build customizations and which tools and libraries you use in your projects. Using coding standards allows you to eliminate the personal preferences of the individual developers from the code which makes it significantly easier to be picked up by other members of your team. Also your coding standards reflect the experience your team gathered over the years allowing you to build customizations more efficiently and of better quality.

現在までに利用できる他の SharePoint カスタマイズ モデルとは異なり、SharePoint Framework はクライアント側の開発に焦点を合わせています。SharePoint Framework では、厳密な決まりではないものの、TypeScript の使用が推奨されています。これにより、開発者はより優れたコードを作成したり、ビルド プロセスで既に存在する不整合をキャッチしたりできます。同じタスクを実行するために利用できるクライアント側ライブラリは何百もあります。チームがこれまでにクライアント側の開発を実行したことがある場合、特定のライブラリを使用するための優先設定があるかもしれません。まだない場合には、いくつかの有名なライブラリを調査して、チームまたは組織全体用のライブラリを 1 つ選択すると、とても役立ちます。Unlike other SharePoint customization models available to date, SharePoint Framework focuses on client-side development. While not strictly required, SharePoint Framework recommends using TypeScript to help developers write better code and catch any inconsistencies already in the build process. There are also hundreds of client-side libraries available to accomplish the same task. If your team has done client-side development in the past, you might already have preference for a particular library. If not, it would be highly beneficial for you to research a few of the most popular libraries and pick one for your team or preferably the whole organization.

すべてのプロジェクトで同じライブラリを使用することによって、新たなチーム メンバーが容易に作業に加わり、プロジェクト間でチーム メンバーを交換できます。クライアント側の開発で経験を積むにつれて、組織はすべてのプロジェクトにおいてその恩恵を受けることができるようになります。また、組織全体でプロジェクトを標準化すると、配信までの時間を短縮し、プロジェクトの維持コストを抑えることができます。新たなライブラリが日々、インターネット上に公開されているため、さまざまな最新のライブラリを代わる代わる使用すると、質の悪いソリューションを非効率的な方法で配信することになります。By using the same library in all your projects you make it easier to onboard new team members and exchange team members between projects. As you gain more experience with client-side development, your organization will be able to benefit of it across all its projects. Standardizing your projects across the whole organization also shortens the time of delivery and lowers the costs of maintenance of your projects. New libraries are published on the internet every day and if you keep switching between the latest libraries you will find yourself working inefficiently delivering solutions of poor quality.

また、組織で使用するライブラリを標準化すると、ソリューションのパフォーマンスを最適化できます。組織全体で同じライブラリが使用されるため、ユーザーは一度ライブラリをダウンロードするだけで済みます。ソリューションの読み込み時間が大幅に短くなり、結果としてユーザー エクスペリエンスが向上します。Standardizing which libraries are used across your organization additionally helps you optimize the performance of your solutions. Because the same library is used across the whole organization, users only need to download it once, what significantly decreases the loading time of the solutions improving the user experience as the result.

有名ないずれかのライブラリを選択すると、そのライブラリを長期にわたり使用し、これから経験する可能性が高い多くの問題を既に解決してきた他の開発者の知識と経験を再利用できます。また、そのような人気のあるライブラリには、チームが採用できるコーディング標準が存在します。特定のライブラリに関する既存の市場標準を使用すると、組織が新たに開発者を雇用し、それらの開発者の生産性を時間をかけずに高めることによって、チームを容易に成長させることができます。Choosing one of the most popular libraries allows you to reuse the knowledge and experience of other developers who have been using that library for a longer period of time and have already solved many of the issues you will likely experience yourself. Also for the most popular libraries there are coding standards available that your team could adopt. By using existing market standards for the particular library you make it easier for your organization to grow your team by hiring developers and helping them become productive faster.

たとえば、SharePoint Framework のファースト パーティ ソリューションをビルドするため、Microsoft は React を選択しました。また OneDrive や Delve などの Microsoft の多数の他のチームもプロジェクトで React を使用しています。これはご使用の SharePoint Framework プロジェクトでも React を使用する必要があるということではありませんが、組織で動作するクライアント側ライブラリの選択の重要性を示しています。たとえば、チームで Angular または Knockout の使用経験がある場合には、SharePoint Framework ソリューションをビルドするときにその経験を活かし、生産性を維持できます。For example, for building first-party solutions on the SharePoint Framework, Microsoft chose React. Also many other teams at Microsoft such as OneDrive or Delve use React in their projects. This doesn't mean that you should be using React in all your SharePoint Framework projects as well, but it proves the importance of choosing a client-side library that works for your organization. If your team has for example experience with Angular or Knockout, there is no reason why you shouldn't benefit of that experience and stay productive when building SharePoint Framework solutions.

ソリューションのライフサイクル全体にわたるコーディング標準とポリシーの適用Enforce coding standards and policies throughout the whole lifecycle of your solution

コーディング標準を使用することには確かに利点がありますが、単にコーディング標準を設定するだけでは、SharePoint カスタマイズの開発とテストのプロセス全体でそれらの標準を積極的に使用することにはなりません。開発者の対応が遅れるほど、チームのコーディング標準と組織のポリシーにソリューションが準拠していることをチームが検証するのは困難になり、プロジェクトで発見された欠陥を修正するためのコストも高くなります。SharePoint ソリューションに対する管理計画を適用するために、開発プロセスの一環としてチームが使用するべきいくつかの手段を以下に記します。Using coding standards offers you clear advantages, but just having coding standards doesn't mean that they are being actively used throughout the whole development and testing process of a SharePoint customization. The longer developers wait and the harder it is for your team to verify that your solution adheres to your team's coding standards and organizational policies, the more costly it will be to fix any defects discovered in the project. Following are a few means that your team should use as a part of their development process to enforce the governance plan for the SharePoint solution.

lint 実行Linting

lint 実行は、コードが特定の規則に従っていることを検証するプロセスです。既定では、SharePoint Framework プロジェクトは TypeScript を使用してビルドされます。TypeScript の lint プログラムである TSLint は、それぞれのビルド時に、事前定義されているルール セットに照らしてプロジェクトを分析し、不整合を報告します。開発者は、有効にするルールを選択し、必要な場合にはチームまたは組織のガイドラインを反映する独自のルールを作成できます。Linting is the process of verifying that the code meets specific rules. By default SharePoint Framework projects are built using TypeScript. On each build TSLint - the linter for TypeScript, analyzes the project against the predefined set of rules and reports any inconsistencies. Developers can choose which rules they want to enable and if necessary can build their own rules that reflect their team's or organization's guidelines.

lint 実行によって開発者が検証できるのは、TypeScript ファイルの内容だけではありません。CSS、JavaScript、Markdown などの有名なほとんどの言語に関して利用できる lint プログラムがあります。チームがこれらの言語に関する特定のガイドラインを設定している場合、lint プログラムでそれらのガイドラインを実装し、プロジェクトを開発者がビルドするたびに自動的に検証できるようにすると役立ちます。Developers can use linting to verify not only the contents of TypeScript files. There are linters available for most popular languages such as CSS, JavaScript or Markdown, and if your team has specific guidelines for these languages it would be beneficial to implement them in a linter so that they can be validated automatically every time a developer builds the project.

自動化されたテストAutomated testing

自動化されたテストを使用すると、プロジェクトに最新の変更を適用した後に簡単に検証を行うことができ、すべての要素がその後も予期どおりに動作します。プロジェクトが大きくなるにつれて、自動化されたテストの重要性が増します。コード ベースが拡張すると、すべての変更がコードの他の部分に及ぼす影響とリスクが大きくなります。自動化されたテストを行うと、開発者は、ソリューションが適切に作動することを検証し、問題となる可能性がある点を早期にキャッチできます。Using automated tests developers can easily verify that after applying the latest changes to the project, all elements continue working as expected. As the project grows so does the importance of automated tests: with the code base expanding every change has bigger impact and risk of affecting some other pieces of code. Automated tests allow developers to verify that the solution works correctly and catch any possible issues early on.

SharePoint Framework には、Karma テスト実行プログラムと、開発者がテストの作成に使用できる Mocha フレームワークのための標準サポートが備わっています。必要な場合には、開発者は PhantomJS などの SharePoint Framework に付属の他のツールを使用して、テスト範囲を広げることができます。SharePoint Framework プロジェクト内のすべてのテストは、標準の gulp test タスクを使用して実行できます。SharePoint Framework offers standard support for the Karma test runner and the Mocha framework that developers can use to write tests. If necessary developers can use additional building blocks provided with the SharePoint Framework such as PhantomJS to further extend the coverage of their tests. All tests in the SharePoint Framework projects can be run using the standard gulp test task.

コード分析Code analysis

lint は特定のファイルの構文を検証するのに役立ちますが、プロジェクト全体がガイドラインに従っていることを検証するために、開発者は多くの場合、さらなるサポートを必要としています。一般に、lint プログラムはコード自体に焦点を当てますが、特定のコード ファイルが示すコンテキストには注目しません。SharePoint Framework ソリューションでは、成果物には特定の要件があります。たとえば、Web パーツはプロジェクト内で一意の ID を持っている必要があります。また、組織には、CDN からスクリプトを参照しない、決められたライブラリの特定のバージョンのみを使用するなどの要件がある場合があります。このような場合、lint プログラムでは不足で、他のツールが必要になります。Where linting is helpful to validate the syntax of the particular file, often developers need more support in order to verify that the project as a whole meets the guidelines. Generally linters focus on the code itself but miss the context of what the particular code file represents. In SharePoint Framework solutions artifacts have specific requirements, for example a web part should have a unique ID in the project. Also organizations might have other requirements such as not referencing scripts from CDN or only using a specific version of a particular library. This is where linters generally fall short and developers need other tools.

SharePoint Code Analysis Framework (SPCAF) は、SharePoint カスタマイズが組織の品質ガイドラインを満たしていることを検証するために、品質保証とセキュリティの役割を担う SharePoint 開発者、管理者、従業員がよく使用するサード パーティ製ソリューションです。SharePoint Code Analysis Framework (SPCAF) is a third party solution frequently used by SharePoint developers, administrators and employees in quality assurance and security roles to verify that SharePoint customizations meet organizational quality guidelines. SPCAF はアプリケーションのライフサイクル プロセス全体を統合して、組織が SharePoint カスタマイズの全体としての所有コストを減らすことができます。SPCAF integrates with the whole application lifecycle process helping organizations lower the total cost of ownership of SharePoint customizations. SPCAF には、SharePoint Framework ソリューションを特に対象としたルール セットがあります。SPCAF offers a set of rules that specifically target SharePoint Framework solutions.

SharePoint Framework プロジェクトのアップグレードUpgrading SharePoint Framework projects

通常、運用環境に SharePoint カスタマイズを展開するだけで、ライフサイクルが終わるということはありません。ソリューションの変更に先立って、要件が変更されたり、新しい要件が追加されたりすることがよくあります。以前に運用環境に展開したカスタマイズを適切に更新するには、開発者はいくつかの事柄を考慮する必要があります。Deploying a SharePoint customization to production usually doesn't mean the end of its lifecycle. Frequently the requirements change or new requirements are added in both cases leading to changes in the solution. To properly update a customization previously deployed to production developers have to take a number of things into account.

セマンティック バージョン管理 (SemVer)Semantic versioning (SemVer)

若干の例外があるものの、SharePoint Framework ではバージョン番号を追跡するためにセマンティック バージョン管理 (SemVer) を使用します。セマンティック バージョン管理は、世界中のソフトウェア開発者の多くが採用しているバージョン管理パターンです。SemVer 番号は MAJOR.MINOR.PATCH の 3 つの番号とオプションのラベルで構成され、1.0.1 などとなります。With a few exceptions SharePoint Framework uses semantic versioning (SemVer) for tracking version numbers. Semantic versioning is a versioning pattern widely adopted by software developers worldwide. A SemVer number consists of three numbers MAJOR.MINOR.PATCH and optional labels, eg. 1.0.1.

注意

現在 SharePoint Frameworks でサポートされているのは、ラベルのない 3 つの番号のみです。Currently SharePoint Frameworks supports only the usage of the three numbers without labels.

SemVer 番号の各部分は、ソリューションに追加される変更の種類に応じて次のように増加します。Different parts of a SemVer number are increased depending on the type of change applied to the solution:

  • MAJOR: 下位互換性がない変更の場合MAJOR, if the changes are not backwards-compatible
  • MINOR: 下位互換性がある新しい機能が導入された変更の場合MINOR, if the changes introduce new functionality that is backwards-compatible
  • PATCH: 下位互換性があるバグ修正プログラムによる変更の場合PATCH, if the changes are backwards-compatible bug fixes

SemVer は単に規約に過ぎないことを念頭に置いてください。最新リリースにおける変更内容を明確にするためにこの規約に従うかどうかはチームで決定できます。It's important to keep in mind that SemVer is merely a contract. It's up to your team to follow it to make clear the changes in the latest release.

セマンティック バージョン管理について詳しくは、http://semver.org をご覧ください。You can read more about semantic versioning at http://semver.org.

バージョン番号の増加Increase version number

SharePoint Framework ソリューションの一部を更新する場合、開発者は関係する部分のバージョン番号を増やし、変更された要素と、その変更によってどんな影響があるかを明確にする必要があります。When updating a part of a SharePoint Framework solution, developers should increase version numbers of the affected pieces to clearly denote which elements have changed and what the impact of the changes is.

package.json のパッケージ バージョンの増加Increase package version in package.json

SharePoint Framework パッケージは Node.js パッケージと同様に構造化されています。SharePoint Framework package is structured like a Node.js package. その依存関係とメタデータは、プロジェクト フォルダー内の package.json ファイルに格納されます。Its dependencies and metadata are stored in the package.json file in the project folder. package.json ファイルのプロパティの 1 つが、プロジェクト全体のバージョンを示すバージョン プロパティです。One of the properties in the package.json file is the version property that denotes the version of the whole project. 既定では、現在のソリューションのすべてのコンポーネントは、このバージョン番号をそのまま継承します。By default, all components in the current solution inherit this version number as their version. 開発者は、プロジェクトの新しいリリースが計画されるたびに SemVer 規約に従って package.json ファイル内のバージョン番号を増やす必要があります。Developers should increase the version number in the package.json file every time a new release of the project is planned following the SemVer convention.

package-solution.json 内のソリューション パッケージ バージョンの増加Increase solution package version in package-solution.json

SharePoint Framework ソリューションは、SharePoint テナントのアプリ カタログにインストールされている .sppkg ファイルを使用して展開されます。SharePoint Framework solutions are deployed using an .sppkg file installed in the App Catalog on a SharePoint tenant. .sppkg ファイルは SharePoint アドイン パッケージに似ていて、同じバージョン管理規約に従います。An .sppkg file is similar to a SharePoint add-in package and follows the same versioning conventions. .sppkg パッケージの現行バージョンは、4 つの部分 (MAJOR.MINOR.REVISION.BUILD) で構成される番号によって定義され、config/package-solution.json ファイルに格納されます。The current version of the .sppkg package is defined using a four-part (MAJOR.MINOR.REVISION.BUILD) number stored in the config/package-solution.json file. わかりやすくするため、開発者は、この番号を package.json ファイルのバージョン番号と同期し、両方の番号ともプロジェクト全体のバージョンを表すようにします。For clarity, developers should keep this number in sync with the version number in the package.json file as both number refer to the version of the project as a whole.

注意

SharePoint で新しいバージョンのパッケージが適切に展開されるようにするには、次のリリースまでの間に package-solution.json ファイルのバージョン番号を増やす必要があります。Increasing the version number in the package-solution.json file between releases is required in order for the new version of the package to be correctly deployed in SharePoint.

依存関係の更新Update dependencies

SharePoint Framework プロジェクトを更新する 1 つの理由は、Angular がバグ修正やパフォーマンスの改善のために新しくリリースされたなど、基礎となる依存関係のいずれかにおける変更です。チームが依存関係のバージョン ロックに関して推奨されている npm shrinkwrap を使用した方法に従っている場合、npm install <package>@<version> --save コマンドを使用して、特定のバージョンに依存関係を更新し、最新の更新によって予期したとおりにプロジェクトが動作することをテストして検証します。基礎となる依存関係に対する変更がプロジェクトに与える影響によって、プロジェクト全体の更新が修正プログラムだけで済む場合やメジャー リリースが必要になる場合などさまざまです。One of the reasons for an update of a SharePoint Framework project might be a change to one of the underlying dependencies, for example a new release of Angular with bug fixes and performance improvements. If your team follows the recommended approach of using npm shrinkwrap for locking dependencies' versions then you would use the npm install <package>@<version> --save command to update your dependency to the specific version and test your project to verify that it works as expected with the latest updates. Depending on how the changes to the underlying dependencies impact the project, the overall project update might vary from a patch to a full major release.

重要

package.json ファイル内の依存関係のバージョン番号を手動で変更しないでください。Don't modify the version numbers of dependencies in the package.json file manually. npm shrinkwrap などのロック ファイルを使用している場合、package.json ファイルに対する手動での変更は無視され、代わりにロック ファイルに記録されているバージョン番号が使用されます。そうなると、プロジェクト内のエラーの追跡が困難になります。If you're using a lock file such as npm shrinkwrap, your manual changes to the package.json file will be ignored and the version numbers recorded in the lock files will be used instead which will lead to hard to track errors in your project.

プロジェクト構造の変更への注意Mind project structure changes

プロジェクトを SharePoint Framework の新しいバージョンに更新すると、プロジェクト構造やプロジェクトの構成ファイルへの変更が必要になる場合があります。Updating your project to a newer version of the SharePoint Framework, might require changes to your project structure and project configuration files. プロジェクトの依存関係で SharePoint Framework のバージョンを更新する前に、必ずアップグレードする SharePoint Framework のバージョンを使用して新しいプロジェクトを作成し、その構造と内容を既存のプロジェクトと慎重に比較する必要があります。Before updating the versions of the SharePoint Framework in your project dependencies, you should always create a new project using the version of the SharePoint Framework to which you want to upgrade and carefully compare its structure and contents with your existing project. そうすれば、その更新がプロジェクトに及ぼす影響を判断でき、プロジェクトに影響する重大な変更を適用してしまうことを防ぐのに役立ちます。This will allow you to determine the impact of the upgrade on your project and help you avoid applying breaking changes to your project.

npm outdated の使用上の注意Beware of using npm outdated

プロジェクト内で更新の必要がある依存関係を見極める 1 つの方法は、npm outdated コマンドを実行することです。One of the ways to find out which dependencies in your project need updating, is to run the npm outdated command. このコマンドにより依存関係ツリーをスキャンし、更新すべきパッケージを表示できます。This command will scan your dependency tree and will show you which packages could be updated. このコマンドの使用は便利ですが、慎重に行う必要があります。While using this command is convenient, it has to be done with caution.

バージョン 1.3 以降では、SharePoint Framework Yeoman ジェネレーターを使用して、SharePoint Online でのみ動作するプロジェクトをスキャフォールディングするか、または SharePoint 2016 Feature Pack 2 以上と SharePoint Online 両方で動作するプロジェクトをスキャフォールディングするかを選択できます。Starting from version 1.3, the SharePoint Framework Yeoman generator allows you to choose whether you want to scaffold a project that should work only in SharePoint Online or in both SharePoint 2016 Feature Pack 2 and up and SharePoint Online. オンプレミスでホストされている SharePoint では、SharePoint Online で使用可能な最新のバージョンより古いバージョンの SharePoint Framework を使用します。SharePoint hosted on-premises uses an older version of the SharePoint Framework than the latest version available in SharePoint Online. オンプレミスの SharePoint と互換性のあるプロジェクトにnpm outdated コマンドを実行すると、中心的な SharePoint Framework パッケージをすべて、npm に発行された最新のバージョンに更新するよう推奨される場合があります。If you would run the npm outdated command on a project compatible with SharePoint on-premises, it would suggest updating all core SharePoint Framework packages to the latest versions published to Npm. しかし、これらのパッケージを最新バージョンに更新することにより、プロジェクトがオンプレミスの SharePoint で機能しなくなることがあります。Unfortunately, by updating these packages to their latest versions, your project wouldn't work with SharePoint on-premises anymore. SharePoint Framework パッケージのバージョンを更新する前に、オンプレミスでホストされている SharePoint でプロジェクトを動作させるかどうか、またその場合に、サポートする必要がある SharePoint Framework のバージョンを必ず確認してください。Before updating the versions of the SharePoint Framework packages, you should always verify if your project is meant to work with SharePoint hosted on-premises and if so, what version of the SharePoint Framework you have to support.

リリース モードでのプロジェクトのビルドとパッケージ化Build and package project in release mode

ソリューションが予期どおりに動作することを検証したら、gulp bundle --ship コマンドを使用してプロジェクトをリリース モデルでビルドします。その後、gulp package-solution --ship コマンドを使用して新しいパッケージを作成します。gulp bundle --ship コマンドを先に実行しないと、パッケージには以前のバージョンのプロジェクトが入ります。Once you verified that the solution is working as expected, build the project in release mode using the gulp bundle --ship command. Then create a new package using the gulp package-solution --ship command. Without running the gulp bundle --ship command first, the package will include previous version of your project.

新しいバージョンのソリューションの展開Deploy new version of your solution

プロジェクトのビルドとパッケージ化の後、次のステップとしてプロジェクトを展開します。最初に、プロジェクトの ./temp/deploy フォルダーにある、更新済み Web パーツ バンドルを展開します。以前のバージョンのソリューションの Web パーツ バンドルの隣にあるファイルを公開します。After building and packaging the project the next step is to deploy it. First deploy the updated web part bundles located in the ./temp/deploy folder in your project. Publish the files next to web part bundles of the previous version of your solution.

注意

以前のバージョンのソリューションは、それらを使用する Web パーツ インスタンスがアクティブである限りは、削除しないでください。You shouldn't remove the previous versions of your solution as long as there are active instances of web parts using them. 各バージョンのバンドル ファイルには一意の名前があり、Web パーツを更新する前に前のバージョンを削除すると、それらの Web パーツが破損します。Each version of the bundle files has a unique name and removing previous versions before updating web parts will break these web parts.

次に、新しいソリューション パッケージを SharePoint アプリ カタログに展開します。これは、適用する必要がある新しいバージョンのソリューションを SharePoint に通知するために必要です。Next, deploy the new solution package to SharePoint app catalog. This is necessary to notify SharePoint of the new version of the solution which it should apply.