MSBuild のコンパイラ オプション

概要

ASP.NET Core プロジェクトなど、TypeScript を使用する MSBuild ベースのプロジェクトがある場合、`tsconfig.json` またはプロジェクト設定のいずれかの方法で TypeScript を構成できます。

`tsconfig.json` の使用

可能であれば、プロジェクトに `tsconfig.json` を使用することをお勧めします。既存のプロジェクトにこれを追加するには、プロジェクトに新しい項目を追加します。これは、最新の Visual Studio バージョンでは「TypeScript JSON 構成ファイル」と呼ばれています。

新しい `tsconfig.json` は、ファイルや構成などの TypeScript 固有のビルド情報の信頼できる情報源として使用されます。 TSConfig の使用方法についてはここで確認できます。また、包括的なリファレンスはこちらにあります。

プロジェクト設定の使用

プロジェクトの設定内で TypeScript の構成を定義することもできます。これは、` .csproj` の XML を編集して、ビルドの動作方法を記述する `PropertyGroup` を定義することで行われます。

xml
<PropertyGroup>
  <TypeScriptNoEmitOnError>true</TypeScriptNoEmitOnError>
  <TypeScriptNoImplicitReturns>true</TypeScriptNoImplicitReturns>
</PropertyGroup>

一般的な TypeScript 設定には、一連のマッピングがあります。これらは、TypeScript cli オプションに直接マップされる設定であり、より分かりやすいプロジェクトファイルを作成するのに役立ちます。各マッピングの値とデフォルトについては、TSConfig リファレンスを参照してください。

CLI マッピング

MSBuild 構成名	TSC フラグ
<TypeScriptAllowJS>	--allowJs
JavaScript ファイルをプログラムの一部として許可します。これらのファイルからエラーを取得するには、`checkJS` オプションを使用します。
<TypeScriptRemoveComments>	--removeComments
コメントの出力の無効化。
<TypeScriptNoImplicitAny>	--noImplicitAny
暗黙的な `any` 型を持つ式と宣言に対するエラーレポートを有効にします。
<TypeScriptGeneratesDeclarations>	--declaration
プロジェクト内の TypeScript と JavaScript ファイルから .d.ts ファイルを生成します。
<TypeScriptModuleKind>	--module
生成されるモジュールコードを指定します。
<TypeScriptJSXEmit>	--jsx
生成される JSX コードを指定します。
<TypeScriptOutDir>	--outDir
出力されたすべてのファイルの出力フォルダを指定します。
<TypeScriptSourceMap>	--sourcemap
出力された JavaScript ファイルのソースマップファイルを作成します。
<TypeScriptTarget>	--target
出力された JavaScript の JavaScript 言語バージョンを設定し、互換性のあるライブラリ宣言を含めます。
<TypeScriptNoResolve>	--noResolve
TypeScript がプロジェクトに追加するファイルの数を増やすのを防ぎます。
<TypeScriptMapRoot>	--mapRoot
デバッガが生成された場所ではなく、マップファイルを見つける場所を指定します。
<TypeScriptSourceRoot>	--sourceRoot
デバッガが参照ソースコードを見つけるルートパスを指定します。
<TypeScriptCharset>	--charset
非推奨。以前のバージョンでは、ファイルの読み取りのためのテキストエンコーディングを手動で設定していました。
<TypeScriptEmitBOM>	--emitBOM
出力ファイルの先頭に UTF-8 バイトオーダーマーク (BOM) を出力します。
<TypeScriptNoLib>	--noLib
デフォルトの lib.d.ts を含むすべてのライブラリファイルを含めないようにします。
<TypeScriptPreserveConstEnums>	--preserveConstEnums
生成されたコードで `const enum` 宣言の消去を無効にします。
<TypeScriptSuppressImplicitAnyIndexErrors>	--suppressImplicitAnyIndexErrors
インデックスシグネチャがないオブジェクトにインデックスを付ける際の `noImplicitAny` エラーを抑止します。
<TypeScriptNoEmitHelpers>	--noEmitHelpers
コンパイル済み出力で `__extends` などのカスタムヘルパー関数の生成を無効にします。
<TypeScriptInlineSourceMap>	--inlineSourceMap
出力された JavaScript 内にソースマップファイルを含めます。
<TypeScriptInlineSources>	--inlineSources
出力された JavaScript 内のソースマップにソースコードを含めます。
<TypeScriptNewLine>	--newLine
出力するファイルの改行文字を設定します。
<TypeScriptIsolatedModules>	--isolatedModules
他のインポートに依存せずに、各ファイルが安全にトランスパイルできることを保証します。
<TypeScriptEmitDecoratorMetadata>	--emitDecoratorMetadata
ソースファイル内のデコレートされた宣言のデザインタイプメタデータを出力します。
<TypeScriptRootDir>	--rootDir
ソースファイル内のルートフォルダを指定します。
<TypeScriptExperimentalDecorators>	--experimentalDecorators
TC39 stage 2 ドラフトデコレーターの実験的なサポートを有効にします。
<TypeScriptModuleResolution>	--moduleResolution
TypeScriptが指定されたモジュール指定子からファイルをどのように検索するかを指定します。
<TypeScriptSuppressExcessPropertyErrors>	--suppressExcessPropertyErrors
オブジェクトリテラルの作成中に、余分なプロパティエラーの報告を無効にします。
<TypeScriptReactNamespace>	--reactNamespace
createElement に対して呼び出されるオブジェクトを指定します。これは、react JSX 出力ターゲットの場合にのみ適用されます。
<TypeScriptSkipDefaultLibCheck>	--skipDefaultLibCheck
TypeScriptに含まれる.d.tsファイルの型チェックをスキップします。
<TypeScriptAllowUnusedLabels>	--allowUnusedLabels
使用されていないラベルに関するエラーレポートを無効にします。
<TypeScriptNoImplicitReturns>	--noImplicitReturns
関数内で明示的に返されていないコードパスに関するエラーレポートを有効にします。
<TypeScriptNoFallthroughCasesInSwitch>	--noFallthroughCasesInSwitch
switch文のフォールスルーケースに関するエラーレポートを有効にします。
<TypeScriptAllowUnreachableCode>	--allowUnreachableCode
到達不可能なコードに関するエラーレポートを無効にします。
<TypeScriptForceConsistentCasingInFileNames>	--forceConsistentCasingInFileNames
インポートでケースが正しいことを保証します。
<TypeScriptAllowSyntheticDefaultImports>	--allowSyntheticDefaultImports
モジュールにデフォルトエクスポートがない場合でも、「import x from y」を許可します。
<TypeScriptNoImplicitUseStrict>	--noImplicitUseStrict
出力されたJavaScriptファイルへの「use strict」ディレクティブの追加を無効にします。
<TypeScriptLib>	--lib
ターゲットランタイム環境を記述するバンドルされたライブラリ宣言ファイルのセットを指定します。
<TypeScriptBaseUrl>	--baseUrl
ベアスペシファイアモジュール名を解決するためのベースディレクトリを指定します。
<TypeScriptDeclarationDir>	--declarationDir
生成された宣言ファイルの出力ディレクトリを指定します。
<TypeScriptNoImplicitThis>	--noImplicitThis
this に型 any が与えられた場合にエラーレポートを有効にします。
<TypeScriptSkipLibCheck>	--skipLibCheck
すべての.d.tsファイルの型チェックをスキップします。
<TypeScriptStrictNullChecks>	--strictNullChecks
型チェック時に、null と undefined を考慮します。
<TypeScriptNoUnusedLocals>	--noUnusedLocals
ローカル変数が読み取られない場合にエラーレポートを有効にします。
<TypeScriptNoUnusedParameters>	--noUnusedParameters
関数パラメータが読み取られない場合にエラーを発生させます。
<TypeScriptAlwaysStrict>	--alwaysStrict
常に「use strict」が出力されるようにします。
<TypeScriptImportHelpers>	--importHelpers
プロジェクトごとに一度、tslib からヘルパー関数をインポートすることを許可し、ファイルごとに含めることを避けられます。
<TypeScriptJSXFactory>	--jsxFactory
React JSX 出力ターゲットで使用される JSX ファクトリ関数を指定します（例： 'React.createElement' または 'h'）。
<TypeScriptStripInternal>	--stripInternal
JSDoc コメントに@internal が含まれる宣言の出力 を無効にします。
<TypeScriptCheckJs>	--checkJs
型チェックされたJavaScriptファイルでのエラーレポートを有効にします。
<TypeScriptDownlevelIteration>	--downlevelIteration
より互換性のある、ただし冗長でパフォーマンスの低いJavaScriptを繰り返し処理のために出力します。
<TypeScriptStrict>	--strict
すべての厳格な型チェックオプションを有効にします。
<TypeScriptNoStrictGenericChecks>	--noStrictGenericChecks
関数型でのジェネリックシグネチャの厳格なチェックを無効にします。
<TypeScriptPreserveSymlinks>	--preserveSymlinks
シンボリックリンクをrealpathに解決することを無効にします。これは、nodeの同じフラグと関連しています。
<TypeScriptStrictFunctionTypes>	--strictFunctionTypes
関数を割り当てるときに、パラメータと戻り値がサブタイプ互換性があることを確認します。
<TypeScriptStrictPropertyInitialization>	--strictPropertyInitialization
宣言されているがコンストラクタで設定されていないクラスプロパティをチェックします。
<TypeScriptESModuleInterop>	--esModuleInterop
CommonJSモジュールのインポートを容易にするために追加のJavaScriptを出力します。これにより、型互換性のためにallowSyntheticDefaultImportsが有効になります。
<TypeScriptEmitDeclarationOnly>	--emitDeclarationOnly
d.tsファイルのみを出力し、JavaScriptファイルは出力しません。
<TypeScriptKeyofStringsOnly>	--keyofStringsOnly
keyof が文字列、数値、またはシンボルではなく、文字列のみを返すようにします。レガシーオプションです。
<TypeScriptUseDefineForClassFields>	--useDefineForClassFields
ECMAScript標準に準拠したクラスフィールドを出力します。
<TypeScriptDeclarationMap>	--declarationMap
d.tsファイルのソースマップを作成します。
<TypeScriptResolveJsonModule>	--resolveJsonModule
.jsonファイルのインポートを有効にします。
<TypeScriptStrictBindCallApply>	--strictBindCallApply
bind、call、およびapplyメソッドの引数が元の関数と一致することを確認します。
<TypeScriptNoEmitOnError>	--noEmitOnError
型チェックエラーが報告された場合、ファイルの出力 を無効にします。

追加のフラグ

MSBuildシステムは引数をTypeScript CLIに直接渡すため、上記の対応付けがない特定のフラグを指定するために、オプションTypeScriptAdditionalFlagsを使用できます。

たとえば、これによりnoPropertyAccessFromIndexSignatureが有効になります。

xml
<TypeScriptAdditionalFlags> $(TypeScriptAdditionalFlags) --noPropertyAccessFromIndexSignature</TypeScriptAdditionalFlags>

デバッグビルドとリリースビルド

PropertyGroup条件を使用して、異なる設定のセットを定義できます。たとえば、一般的なタスクは、本番環境でコメントとソースマップを削除することです。この例では、異なるTypeScript構成を持つデバッグとリリースのPropertyGroupを定義します。

xml
<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <TypeScriptRemoveComments>false</TypeScriptRemoveComments>
  <TypeScriptSourceMap>true</TypeScriptSourceMap>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <TypeScriptRemoveComments>true</TypeScriptRemoveComments>
  <TypeScriptSourceMap>false</TypeScriptSourceMap>
</PropertyGroup>
<Import
    Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets"
    Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets')" />

ToolsVersion

プロジェクトファイル内の<TypeScriptToolsVersion>1.7</TypeScriptToolsVersion>プロパティの値は、ビルドに使用されるコンパイラバージョン（この例では1.7）を識別します。これにより、異なるマシンで同じバージョンのコンパイラに対してプロジェクトをビルドできます。

TypeScriptToolsVersionが指定されていない場合、マシンにインストールされている最新のコンパイラバージョンがビルドに使用されます。

新しいバージョンのTSを使用しているユーザーは、最初にロードするときにプロジェクトをアップグレードするように促されます。

TypeScriptCompileBlocked

異なるビルドツール（gulp、gruntなど）を使用してプロジェクトをビルドし、開発とデバッグのエクスペリエンスにVSを使用している場合、プロジェクトで<TypeScriptCompileBlocked>true</TypeScriptCompileBlocked>を設定します。これにより、すべての編集サポートが提供されますが、F5を押してもビルドは実行されません。

TypeScriptEnableIncrementalMSBuild（TypeScript 4.2 Beta以降）

デフォルトでは、MSBuildはプロジェクトのソースファイルが前回のコンパイル以降に更新された場合にのみ、TypeScriptコンパイラを実行しようとします。ただし、TypeScriptのincrementalオプションが有効になっている場合など、この動作が問題を引き起こしている場合は、<TypeScriptEnableIncrementalMSBuild>false</TypeScriptEnableIncrementalMSBuild>を設定して、MSBuildの実行ごとにTypeScriptコンパイラが呼び出されるようにします。