Visual StudioでASP.NET CoreプロジェクトのTypeScriptをビルドするなら、結論はMicrosoft.TypeScript.MSBuildをNuGetで導入し、tsconfig.jsonをプロジェクト単位で管理し、dotnet buildやdotnet publishでも同じ成果物が出る状態にすることです。2026年4月のMicrosoft Learn更新は、派手な新機能追加というより、TypeScript SDKからNuGet/MSBuild中心へ移行する方針、tsconfig.json例の見直し、CI/CDでの再現性確認を促す内容として読むべきです。Microsoft Learnの対象ページは現行表示で2026年4月27日更新、GitHub履歴では4月24日にメタデータ関連の更新、4月27日にtsconfig例の更新が確認できます。(Microsoft Learn)
Visual StudioのTypeScript NuGetビルドで押さえるべき更新ポイント
今回の更新で実務上もっとも重要なのは、ASP.NET Core + TypeScript + Visual Studioの組み合わせでは、NuGetパッケージを使ったMSBuild統合が引き続き中心に位置付けられている点です。Microsoft Learnでは、Visual Studio 2019以降はTypeScript SDKではなくNuGetパッケージの利用が推奨され、ASP.NET Coreなどの.NETシナリオではdotnet buildやdotnet publishによるTypeScriptコンパイルを有効にする方法としてNuGetが示されています。(Microsoft Learn)
一方で、すべてのTypeScriptプロジェクトにNuGetを使えばよいわけではありません。JavaScript Project System、つまりJSPSや.esprojベースのプロジェクトでは、NuGetではなくnpmパッケージを使うよう案内されています。Visual Studio 2022ではTypeScript SDKが非推奨とされており、既存プロジェクトもNuGetまたはnpmベースへ整理する流れが明確です。(Microsoft Learn)
2026年4月更新を読む際は、日付の扱いにも注意が必要です。4月24日のコミット履歴には「自動挿入されるメタデータの削除」「所有者情報の更新」が記録されていますが、ビルド設定として目に見える更新は4月27日のtsconfig.json例の変更です。具体的には、compileOnSave、target: "ES6"、rootDir: "./scripts"、outDir: "wwwroot/js"、excludeでnode_modulesとwwwrootを除外する構成が示されています。(GitHub)
NuGetとnpmの使い分け
Visual StudioでTypeScriptを扱うときに迷いやすいのが、「NuGetで入れるべきか、npmで入れるべきか」です。判断基準は、フロントエンドの技術よりもプロジェクトシステムとビルド経路で決めると失敗しにくくなります。
| プロジェクトの種類 | 推奨される方法 | 理由 | 注意点 |
|---|---|---|---|
| ASP.NET Core MVC / Razor Pages / Blazor系でTypeScriptを一部利用 | NuGet | MSBuildやdotnet buildに統合しやすい | tsconfig.jsonのoutDirをwwwroot配下に整理する |
CI/CDでdotnet publishを使って配布物を作るASP.NET Core | NuGet | Visual Studio外でも.NET CLI経由でビルドしやすい | ビルドエージェント上のNode.js有無を確認する |
JSPS / .esprojベースのVisual Studioプロジェクト | npm | Microsoft Learnでnpm利用が案内されている | NuGetを入れても期待どおりに連携しない可能性がある |
| React / Angular / Vue / Viteなどのフロントエンド主体 | npm | Node.jsツールチェーンと相性がよい | ASP.NET Core側とはビルド責務を分ける |
| 古いnon-SDK styleのASP.NET Core | NuGet。ただし既存Importの整理が必要 | MSBuild統合をNuGet側に任せる | Microsoft.TypeScript.Default.propsやMicrosoft.TypeScript.targetsの重複Importに注意 |
実務では「Visual Studioで編集できるか」ではなく、「クリーンな環境でdotnet buildまたはnpm scriptを実行したときに同じ成果物が出るか」を基準にしてください。開発者のPCでは動くのにCIで失敗するケースの多くは、Visual Studioのローカル環境、Node.jsのパス、古いSDK参照、tsconfig.jsonの出力先が混在していることが原因です。
ASP.NET CoreでTypeScriptをNuGetビルドする基本手順
Visual StudioでASP.NET CoreプロジェクトにTypeScriptビルドを組み込む流れは、次の順で進めると安全です。Microsoft Learnでは、NuGetパッケージマネージャーからMicrosoft.TypeScript.MSBuildを追加し、tsconfig.jsonをプロジェクトルートに置く手順が示されています。(Microsoft Learn)
| 手順 | 作業 | 確認ポイント |
|---|---|---|
| 1 | ASP.NET CoreプロジェクトをVisual Studioで開く | .csprojを持つプロジェクトか確認する |
| 2 | NuGetパッケージマネージャーでMicrosoft.TypeScript.MSBuildを追加 | 既存のTypeScript SDK参照と混在させない |
| 3 | tsconfig.jsonをプロジェクトルートに追加 | scriptsなど入力元フォルダーを決める |
| 4 | rootDirとoutDirを明示する | 生成JSが想定外の階層に出ないようにする |
| 5 | Visual Studioのビルド、またはdotnet buildを実行 | wwwroot/jsなどに.jsと.js.mapが生成されるか確認する |
| 6 | dotnet publishでも確認 | 開発PCだけでなく配布成果物でも再現する |
Microsoft.TypeScript.MSBuildのバージョンは、記事やサンプルをそのまま固定値としてコピーするのではなく、プロジェクトのサポート方針に合わせて決めます。Microsoft Learnのサンプルでは5.8.3のPackageReferenceが掲載されていますが、NuGet Galleryでは2026年4月時点で6.0.3が表示されています。導入時は、最新化を優先するのか、組織内で検証済みのバージョンに固定するのかを決めてから反映してください。(Microsoft Learn)
<ItemGroup>
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="6.0.3">
<PrivateAssets>all</PrivateAssets>
</PackageReference>
</ItemGroup>上記はあくまで例です。チームでCentral Package Managementを使っている場合は、.csprojにバージョンを直接書くのではなく、Directory.Packages.propsで一元管理する方が保守しやすくなります。特に複数のASP.NET Coreプロジェクトを持つリポジトリでは、TypeScriptコンパイラのバージョン差がビルド結果や型チェック結果の差につながることがあります。
2026年4月更新で注目したいtsconfig.jsonの考え方
今回の更新で実務的に見直したいのは、tsconfig.jsonのサンプルです。Microsoft Learnの現行例では、TypeScriptファイルをscripts配下に置き、生成されたJavaScriptをwwwroot/jsへ出力する構成が示されています。(Microsoft Learn)
{
"compileOnSave": true,
"compilerOptions": {
"noImplicitAny": false,
"noEmitOnError": true,
"removeComments": false,
"sourceMap": true,
"target": "ES6",
"rootDir": "./scripts",
"outDir": "wwwroot/js"
},
"include": [
"scripts/**/*"
],
"exclude": [
"node_modules",
"wwwroot"
]
}この設定で特に重要なのは、rootDir、outDir、excludeの3つです。
rootDirはTypeScriptの入力元を明確にします。これを省略すると、プロジェクト構成によっては出力先に意図しない階層が作られることがあります。scripts/app.tsをwwwroot/js/app.jsとして出したいなら、rootDirを./scriptsに固定しておくと管理しやすくなります。
outDirは生成されたJavaScriptの出力先です。ASP.NET Coreでは静的ファイルとして配信するため、一般的にはwwwroot/jsのようにwwwroot配下へ出力します。ただし、生成物をGitに含めるかどうかはチームで決めてください。CI/CDで必ずビルドして成果物を作る運用なら、生成済みJSをソース管理に含めない方が差分管理は楽になります。
excludeでwwwrootを除外している点も見落とせません。wwwrootを除外しないと、生成済みJavaScriptや関連ファイルを再処理対象にしてしまい、重複出力や不要なビルド対象の増加につながることがあります。node_modulesも同様に、TypeScriptの入力対象に含めるべきではありません。
noImplicitAnyは公式例ではfalseです。既存コードの移行時には現実的な設定ですが、新規開発や型安全性を重視するプロジェクトではtrueを検討する価値があります。最初から厳しすぎる設定にして開発を止めるより、移行フェーズではfalse、型定義が整った段階でtrueへ引き上げる、という段階的な運用も有効です。
ビルド時に確認すべき出力とデバッグ設定
Visual StudioでBuild > Build Solutionを実行すると、tsconfig.jsonの設定に従ってTypeScriptがコンパイルされます。sourceMapを有効にしている場合、outDirに指定したフォルダーに.jsファイルと.js.mapファイルが生成されます。Microsoft Learnでは、デバッグにSource Mapファイルが必要であることも明記されています。(Microsoft Learn)
確認すべきポイントは次のとおりです。
| 確認項目 | 見る場所 | OKの状態 |
|---|---|---|
| JavaScriptが生成されているか | wwwroot/js | .tsに対応する.jsがある |
| Source Mapが生成されているか | wwwroot/js | .js.mapがある |
| ブラウザーで読み込まれているか | 開発者ツールのNetwork | 404になっていない |
| TypeScriptの行でデバッグできるか | ブラウザー開発者ツールまたはVisual Studio | .tsに近い位置で追跡できる |
| CIでも同じ出力になるか | ビルドログと成果物 | 開発PCと差がない |
「Visual StudioでF5を押すと動くが、dotnet publish後にJavaScriptがない」という場合は、ローカルの生成済みファイルに依存している可能性があります。必ずクリーンな状態でdotnet build、できればdotnet publishまで実行し、成果物の中にwwwroot/jsが含まれるか確認してください。
DevOps engineersとplatform teamsが見直すべき運用ポイント
開発者個人の設定だけでなく、DevOpsやプラットフォームチームは「誰が、どの環境でビルドしても同じ結果になるか」を確認する必要があります。
まず、Microsoft.TypeScript.MSBuildのバージョンをリポジトリで固定します。各開発者がVisual StudioのUIから都度追加すると、プロジェクトごとにTypeScriptのバージョンがずれることがあります。複数プロジェクトを管理するなら、Central Package Managementでバージョンを統一するのが現実的です。
次に、Node.jsの扱いを明確にします。Microsoft Learnでは、Visual Studioがインストールされている環境では同梱のnode.exeが自動的に使われ、Visual Studioがない環境ではNode.jsのインストールが必要になると説明されています。また、Visual Studioが想定と異なるNode.jsやサードパーティツールを使う場合は、外部Webツールのパス設定を確認する必要があります。(Microsoft Learn)
CI/CDでは、次のようなチェックをパイプラインに入れるとトラブルを早期に発見できます。
dotnet restore
dotnet build --configuration Release
dotnet publish --configuration Release --output ./publishビルド後に、publish/wwwroot/js配下のJavaScriptとSource Mapの有無を確認します。単にビルドが成功しただけでは不十分です。Webアプリとして配信される静的ファイルが成果物に含まれているかまで見る必要があります。
グローバルチームで開発している場合は、READMEや開発環境セットアップ手順に「TypeScriptはNuGet/MSBuildでビルドする」「npmはJSPSまたはフロントエンド専用プロジェクトで使う」と明記しておくと混乱を減らせます。英語圏メンバーと共同開発する場合でも、このルールはそのまま通用します。
古いプロジェクトで起きやすいImport重複に注意
古いnon-SDK styleのASP.NET Coreプロジェクトでは、TypeScript関連のMSBuild importが.csprojに直接残っていることがあります。Microsoft Learnでは、NuGetパッケージを使ってMSBuildサポートを追加する場合、Microsoft.TypeScript.Default.propsやMicrosoft.TypeScript.targetsをプロジェクトファイル側で個別にImportしないよう案内されています。これらはNuGetパッケージによって取り込まれるため、重複すると意図しない動作につながる可能性があります。(Microsoft Learn)
削除対象になりやすい記述は、次のようなImportです。
<Import
Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props"
Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props')" />
<Import
Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets"
Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets')" />移行時は、いきなり削除して終わりにするのではなく、次の順で確認してください。
| 作業 | 目的 |
|---|---|
.csprojをバックアップまたはGitで差分管理する | 失敗時に戻せるようにする |
| 古いTypeScript SDK関連のImportを確認する | NuGetとの重複を避ける |
Microsoft.TypeScript.MSBuildを追加する | MSBuild統合をNuGetに寄せる |
dotnet buildを実行する | Visual Studio依存ではないビルドを確認する |
| 出力先のJSを確認する | 移行後も成果物が変わらないか見る |
よくある失敗と対処法
| 症状 | 主な原因 | 対処法 |
|---|---|---|
.jsファイルが生成されない | includeが実ファイルの場所と合っていない | scripts/**/*など入力元フォルダーを見直す |
| 出力先に余計な階層が作られる | rootDirが未指定、または入力元が分散している | rootDirを./scriptsなどに固定する |
wwwroot配下のファイルまで処理される | excludeにwwwrootがない | excludeへwwwrootを追加する |
| デバッグでTypeScriptの行に対応しない | sourceMapが無効、または.js.mapが配布されていない | sourceMap: trueにし、出力ファイルを確認する |
| CIでは失敗するが開発PCでは成功する | Visual Studio同梱Node.jsに依存している | ビルドエージェントにNode.jsを用意し、パスを明確にする |
| npmとNuGetの両方が混在している | プロジェクト種別で使い分けていない | ASP.NET CoreはNuGet、JSPSや.esprojはnpmに整理する |
| 古いプロジェクトでビルドが不安定 | TypeScript関連Importが重複している | .csproj内の古いImportを確認・削除する |
特に注意したいのは、npmとNuGetの混在です。フロントエンド単体プロジェクトの感覚でASP.NET Core側にもnpmのTypeScriptだけを入れると、Visual Studio上では編集できても、dotnet buildやdotnet publishで期待どおりにコンパイルされないことがあります。逆に、JSPSや.esprojにNuGetを入れても、プロジェクトシステムの考え方と合わないため、npmベースに寄せた方が自然です。
既存プロジェクトを見直すチェックリスト
2026年4月更新をきっかけに、既存のVisual Studioプロジェクトでは次の順に点検すると効率的です。
| 対象 | チェック内容 | 判断基準 |
|---|---|---|
| プロジェクト種別 | ASP.NET Coreか、JSPS / .esprojか | ASP.NET CoreならNuGet、JSPSならnpm |
| パッケージ | Microsoft.TypeScript.MSBuildが入っているか | バージョンがチーム方針と一致している |
.csproj | 古いTypeScript SDK importが残っていないか | NuGetと重複していない |
tsconfig.json | rootDir、outDir、include、excludeが明確か | 入力と出力が分離されている |
| ビルド | dotnet buildでJSが生成されるか | Visual Studioなしでも再現できる |
| Publish | 配布成果物にJSが含まれるか | 本番環境で404にならない |
| デバッグ | Source Mapが生成されるか | 開発時にTypeScript側を追える |
| CI/CD | Node.jsとNuGet復元の手順が明確か | クリーン環境で成功する |
このチェックリストで問題が見つかったら、まずはプロジェクト種別の整理から始めてください。NuGetかnpmかの選択を間違えたままtsconfig.jsonだけ調整しても、ビルドの再現性は改善しにくいからです。
次に取るべき行動
Visual StudioでTypeScriptを扱う開発者は、まず自分のプロジェクトがASP.NET Coreなのか、JSPS / .esprojなのかを確認してください。ASP.NET Coreであれば、Microsoft.TypeScript.MSBuildをNuGetで管理し、tsconfig.jsonのrootDirとoutDirを明示し、dotnet buildとdotnet publishで成果物を確認するのが最短ルートです。
DevOps engineersやplatform teamsは、個々の開発者環境ではなく、CI/CD上でTypeScriptコンパイルが再現できるかを基準に見直しましょう。パッケージバージョン、Node.js、生成JSの扱い、Source Mapの出力方針をリポジトリ単位で明文化すれば、Visual Studioの更新や開発者PCの差によるトラブルを減らせます。
2026年4月更新は、破壊的変更を知らせるものというより、Visual StudioにおけるTypeScriptビルドを「SDK依存」から「プロジェクトごとのNuGet/npm管理」へ整理する流れを再確認する材料です。今すぐ行うべきことは、既存プロジェクトのパッケージ、tsconfig.json、CIの出力確認を点検し、ASP.NET CoreではNuGet/MSBuildで一貫してビルドできる状態に整えることです。
コメント