Skip to content

CHEATSHEET.md

Latest commit

 

History

History
473 lines (355 loc) · 24.6 KB

CHEATSHEET.md

File metadata and controls

473 lines (355 loc) · 24.6 KB
Raw

チートシート

手順だけを並べたもの。 理由・詳細・落とし穴の背景は、各項のリンク先が一次情報。

ここは意図的に二重管理している。手順は「思い出すため」に転記し、 判断が要ることは書かない。 迷ったらリンク先を読むこと。

0. ワンライナー集

すべて root\programs で実行する（cd root\programs）。詳しくは右端の節。

検証する

やりたいこと コマンド 節
全部を通しで（ビルド → 単体テスト → 疎通） .\0_RunAll.ps1 1
変えた所に必要な分だけ回す .\SelectTargets.ps1 -Run 1
何が回るかだけ見る .\SelectTargets.ps1 1
全ビルドだけ .\1_BuildAll.ps1 -IgnoreErrors 'error MSB(3482|3325|3321):.*WSClientWinCone_sample\.csproj' 1
単体テストだけ .\2_RunAllTests.ps1 1
疎通だけ .\3_SmokeTest.ps1 1
VB 側を通しで .\0_RunAll.ps1 -Lang VB 3

単体テストを絞る・広げる

やりたいこと コマンド 節
一部だけ回す（名前は部分一致・複数可） .\2_RunAllTests.ps1 -Only "TestBatch", "NUnit" 1
指定できる名前を見る .\2_RunAllTests.ps1 -List 1
Linux でも回す（docker が要る） .\2_RunAllTests.ps1 -Linux 1
DB を Oracle / MySQL / PostgreSQL でも回す .\2_RunAllTests.ps1 -CrossDb -LocalServicesDir D:\path\to\LocalServicesOnDocker 1
カバレッジを測って COVERAGE.md を更新する .\2_RunAllTests.ps1 -Coverage -LocalServicesDir D:\path\to\LocalServicesOnDocker 1

依存パッケージを点検する

やりたいこと コマンド 節
脆弱性のある依存を見る（ビルドの後に） .\CheckVulnerability.ps1 -Detail 1
packages.config と csproj の版を突き合わせる .\ComparePackage.ps1 -Check 1
bindingRedirect と配布物の版を突き合わせる .\CompareRedirect.ps1 -Check 1

リリースする

やりたいこと コマンド 節
版を上げる（変更内容の確認） .\0_SetVersion.ps1 -Version 3.3.0 -WhatIf 2
版を上げる .\0_SetVersion.ps1 -Version 3.3.0 2
NuGet 用にビルドする CS\0_Release4Nuget.bat 2
パッケージを作る CS\NuGet\_NuGetPack.bat 2
作ったパッケージを消す CS\NuGet\_Cleanup.bat 2

その他

やりたいこと コマンド 節
エージェント用のスキルを取ってくる .\GetAgentSkills.ps1 AGENTS.md
2 つの結果ファイルを比べる .\CompareResult.ps1 -Expected <期待> -Actual <実測> TESTING.md 1 節

1. 検証（変更したら必ず）

cd root\programs
.\0_RunAll.ps1                 # 1 → 2 → 3 を順に実行する

個別に回すとき。順序は固定（1 のクリーンとアセンブリ配置が 2・3 の前提）。

.\1_BuildAll.ps1 -IgnoreErrors 'error MSB(3482|3325|3321):.*WSClientWinCone_sample\.csproj'
.\2_RunAllTests.ps1
.\3_SmokeTest.ps1
合格の目安 詳細
ビルド 全ステップ OK BUILDING.md
単体テスト 16/16 OK、差分 0（Golden 8 ＋ NUnit 8。NUnit は失敗 0） TESTING.md
疎通 30/30 OK SMOKETEST.md

既定は C# 側。VB 側は -Lang で回す（3 節）。

2_RunAllTests.ps1 のオプション（詳細は TESTING.md。コンテナを使うものは、付けたときだけ起動する）

オプション 何をするか 要るもの
-Only <名前>[, …] / -List 対象を絞る（部分一致・複数可）／指定できる名前を出す —
-SkipBuild バッチを回さず、手元の結果だけを判定する —
-Linux Golden の EncAndDecUtilCUI と NUnit の TestPublic を、Linux のコンテナでも回す（＋2 ケース） docker
-CrossDb -LocalServicesDir <dir> TestPublicDb を Oracle → MySQL → PostgreSQL の順に 1 つずつ「起動 → 回す → 停止」 docker か WSL2
-Coverage -LocalServicesDir <dir> NUnit の全部・Linux の回・クロス DB を 1 回で回し、全部 OK なら Tests/COVERAGE.md を書き直す docker
-LinuxImage / -LinuxMemory Linux のコンテナのイメージ（既定 mcr.microsoft.com/dotnet/sdk:10.0）／メモリ上限（既定 4g） —

  • -Coverage は -Only / -SkipBuild / -Linux / -CrossDb と同時に指定できない（全部をそろえて測るため）。-Linux と -CrossDb も同時には指定できない

  • 普通の実行は COVERAGE.md を書かない（カバレッジは画面に出すだけ）

  • 1_BuildAll.ps1 を単体で回すときは -IgnoreErrors を付ける。 ClickOnce の署名（MSB3482）で、証明書が無い環境では必ず出る （BUILDING.md 4 節）。 0_RunAll.ps1 は既定でこれを渡すので、付けなくてよい（#555）。 除外した内容は件数つきで別枠に出るため、そちらは目を通すこと

  • 2_RunAllTests.ps1 は Result*.txt を書き換える。差分 0 なら中身は同じ

  • 前提（DB・サービス・IIS Express）は RELEASE.md 2 節

  • 0_RunAll.ps1 は 1・2・3 の実行時間を出す（#571）

通しは長い。反復では絞り込む（#571）

実測（-Lang Both）は 合計 24.6 分で、内訳はこうなっている。

1_BuildAll.ps1     15.5 分  ← 63%。ここが主因
2_RunAllTests.ps1   1.9 分
3_SmokeTest.ps1     7.3 分

環境と状態で振れる。 桁を掴むための目安として見ること。

変更した箇所だけを回す。 通しは最後に 1 回でよい。

.\1_BuildAll.ps1 -Only "WSSrv" -SkipClean    # Clean を挟まない分だけ速い
.\2_RunAllTests.ps1 -Only "TestBatch"        # Result*.txt も絞った分だけ書き換わる
.\3_SmokeTest.ps1 -Only "MVC_Sample" -SkipBuild

-Only に指定できる名前は -List で出す。（#576） -Only は複数指定できる（#610）。

.\3_SmokeTest.ps1 -List          # 対象名の一覧。-Lang が効く
.\2_RunAllTests.ps1 -Only "TestBatch", "NUnit"

回す範囲を差分から割り出す（#610）

「どこまで回すか」は SelectTargets.ps1 が下の対応表どおりに決める。 検証の済んだコミット（.verified-commit。Git 管理外）からの差分を読む。 未コミット・未追跡の変更も含む。

.\SelectTargets.ps1                  # 回す範囲を表示するだけ
.\SelectTargets.ps1 -Run             # その範囲で 1 → 2 → 3。全部 OK なら記録を進める
.\SelectTargets.ps1 -Record          # 通しが通った後に、いまの HEAD を記録する
.\SelectTargets.ps1 -Since develop   # 記録ではなく、指定した基点からの差分で見る
表示 意味
通し 基盤・共通バッチ・対応が引けないファイルに触れている
N 件 変更の下にあるバッチから引いた対象だけ
スクリプトの確認（1 件） 検証スクリプトだけを変えた。軽い対象を 1 件回す
手で確かめるもの どの検証にも載っていない（Else/TestLog、GUI、.sh 等）。回せていないと報告する
  • 記録が無いと止まる。 初回は通しの後に -Record するか、-Since を付ける
  • 手で確かめるものが残ると、-Run が全部 OK でも記録は進まない（終了コード 1）
  • 対象名とバッチの対応は各スクリプトの -List -PassThru から取る（写していない）

段階で回す量を変える（fixing / fixed、#610）

途中（fixing #N）は軽く、完了（fixed #N）の前に全部。 判断の理由は AGENTS.md。

# 編集中（変えたテストだけ。NUnit はフィルタで 1 クラス・1 メソッドに絞れる）
dotnet test CS\Frameworks\Tests\NUnit\TestPublic\TestPublic.csproj -f net10.0 --filter "FullyQualifiedName~SQLUtilityTests"
.\2_RunAllTests.ps1 -Only "TestCode (net10.0)"

.\SelectTargets.ps1 -Stage fixing -Run    # 途中のコミットの前（記録は進まない）
.\SelectTargets.ps1 -Run                  # 完了のコミットの前（既定は fixed。通れば記録が進む）
fixing fixed
DB を使う対象 後回し 回す
基盤に触れたときのビルド 基盤だけ（クリーンを含む 11 ステップ） 通し
基盤に触れたときの疎通 後回し 通し
末端（サンプル・ツール・テスト）の変更 変えたものだけ（DB を使うものは後回し） 変えたものだけ
記録（.verified-commit） 進めない 全部 OK なら進める

  • 後回しにしたものは「後回しにしたもの（fixed で必ず回す）」に一覧で出る。 報告にそのまま書く

  • 記録が fixed でしか進まないので、基点は「最後に fixed で通ったコミット」になる

  • クロス DB・VB・管理者権限は、触れたときだけ回す（AGENTS.md の表）

  • DB のコンテナは LocalServicesOnDocker の CHEATSHEET.md に従う。 必要なものだけを名前で起動し、必須でないものを同時に複数起動しない（クロス DB は SQL Server に 1 つずつ足す）。 使い終わったら止める。メモリを使い切ると、コンテナがシステムごとハングさせる（TESTING.md の冒頭）

  • クロス DB（TestPublicDb）は .\2_RunAllTests.ps1 -CrossDb -LocalServicesDir <LocalServicesOnDocker> で回す（#623）。 DBMS を 1 つずつ起動 → 回す → 停止まで自動で行う（docker が使えれば Rancher 版、使えなければ WSL2 版）。 始める前から動いていた DBMS には触らない。-CrossDb を付けなければ、コンテナは起動も停止もしない

  • カバレッジを Tests/COVERAGE.md に残すなら .\2_RunAllTests.ps1 -Coverage -LocalServicesDir <LocalServicesOnDocker>。 NUnit の全部（Linux の回を含む）とクロス DB を 1 回で回し、全部 OK ならアセンブリごとに合算して書く （OpenTouryo.Framework だけは、TestFramework の対象モジュールごと）。docker が要る。普通の実行は COVERAGE.md を書かない

  • Linux（Golden の EncAndDecUtilCUI と NUnit の TestPublic）は .\2_RunAllTests.ps1 -Linux で回す（#632）。 Windows でビルドした net10.0 の出力を、Linux のコンテナ（1 つ、--rm）でそのまま動かす。docker が要る（TESTING.md 2 節）。 Public・Public.Security に触れた fixed では、SelectTargets.ps1 が自動で付ける（fixing では後回し）

  • dotnet test の -f net10.0 を外すと net48 も回る。net48 / net10.0 で実装が違う箇所は両方回す

  • 基盤だけのビルドでもクリーンは外さない。 外すと #574 の罠 （Business.RichClient (net48) が「does not reference .NETFramework,Version=v4.8」）を踏む。 クリーンは CS 配下の bin / obj をすべて消すので、fixing の後に疎通だけを -SkipBuild で回してはならない

基盤（Public の 4 ファイル）を変えたときの実測（#612、C# のみ）。約 5 分の 1 になる。

fixing : 基盤だけのビルド 1.4 分 ＋ DB を使わない単体テスト 8 件 2.8 分   … 約 4 分
fixed  : 通し（ビルド 8.8 分 ＋ 単体テスト 14 件 約 4 分 ＋ 疎通 30 件 約 9 分） … 約 22 分

どこまで回すかは依存関係で決まる。（#576）

依存の向きは一方向で、段は 2 つしかない。

基盤    NuGet / Business / Business.RichClient / CopyAssemblies
          ↓  （ここが変われば、下は全部やり直し）
末端    Tools / 各サンプル / Tests
変更した場所 1_BuildAll 2_RunAllTests 3_SmokeTest
Infrastructure/（基盤） 通し 通し 通し
Tools/（ツール） -Only Framework_Tool 不要 -Only <そのツール>
個別サンプル -Only <サンプル> 不要 -Only <サンプル>
Tests/Golden Tests/NUnit 不要（2 が自分でビルドする） -Only <対象> 不要
Tests/Else 不要 不要 TestTransmission / TestWebAPIClient だけ -Only <対象>。他は手作業
.md のみ 不要 不要 不要
.ps1 のみ 変えた本を -Only で 1 件 同左 同左

.ps1 は、表示だけの変更でも実行する（#588）。 構文エラーは読んでも分からず、5.1 と 7 で振る舞いが違う （CODING.md 5 節）。 回さなかったなら、そう報告する（「検証済み」と書かない）。

2_RunAllTests.ps1 の対象はフレームワークのテストだけで、 ツールやサンプルを変えても動かない。回す理由が無い。

ツールだけの変更なら、通しの 1/16 ほどで終わる。

基盤のビルド             122.8 秒
Framework_Tool 系だけ     74.8 秒     ← ツールの変更で必要なのはこちら
2_RunAllTests 通し       111.6 秒
2_RunAllTests -Only       35 秒ほど

通しを回す場面の判断は AGENTS.md「回す範囲は、依存関係で決める」。

警告が多いステップの内訳を見る。

.\1_BuildAll.ps1 -Only "Framework_Tool" -SkipClean -WarnDetail

-Only ＋ -SkipClean は万能ではない。（#574 で踏んだ） 前段が用意する状態に依存するステップは、飛ばすと落ちる。

通し（Clean あり）             エラー 0 件
-Only "Business" -SkipClean    Business.RichClient_net48 で
                               「does not reference .NETFramework,Version=v4.8」

変更と無関係なエラーに見えるため、切り分けで時間を失う。 絞り込みで妙なエラーが出たら、まず通しで再現するかを見ること。 再現しなければ、それは絞り込みの制約であって不具合ではない。

パッケージの版を触ったら、次の 2 本も見る（0_RunAll.ps1 は自動で回して警告する）。

.\ComparePackage.ps1 -Check     # packages.config と csproj の版（#569）
.\CompareRedirect.ps1 -Check    # bindingRedirect と配布物の版（#556）

依存パッケージの脆弱性は、ビルドの警告に頼らず別に見る（#610。0_RunAll.ps1 は最後に自動で回して警告する）。

.\CheckVulnerability.ps1 -Detail                          # 推移的な依存を含めた一覧
.\CheckVulnerability.ps1 -IssueDraft "$env:TEMP\vuln.md"  # Issue の文面の下書き（投稿はしない）
  • ビルドの後に回す。 restore 結果が無いと推移的な依存を見られない（「未リストア」として件数が出る）
  • ビルドの NU1901〜NU1904 は restore のときにしか出ず、Dependabot は推移的な依存を見ない（BUILDING.md 13 節）
  • 見つけたら Issue を起こさずにその場で直す（AGENTS.md「依存パッケージの脆弱性を見つけたら」）。-IssueDraft は直せないときだけ

どちらもビルドの後に回す。 復元された DLL を読むため。 1_BuildAll.ps1 は bin を消すので、clean の前に測ると古い残骸を拾う。（#579）

CompareRedirect.ps1 の**「判定不能」は不一致ではない。** 分類のうち**「要調査」だけ**を見ればよい（他は実行時に読まれない）。 読み方は BUILDING.md 12 節。

2. リリース（NuGet 公開）

一次情報は RELEASE.md と CS/NuGet/README.md。

1. develop → master へ PR を出し、マージ（--no-ff）してタグをプッシュ
     master は PR 経由のみ。レビュー 1 名 ＋ CI（build、約 14 分）が要る
2. .\0_SetVersion.ps1 -Version 3.3.0
3. コミット & push                      ← Source Link はこのコミットに固定される
4. CS\0_Release4Nuget.bat               ← 版はアセンブリに焼き込まれる
5. CS\NuGet\_NuGetPack.bat              ← 版の一致（ソース・DLL）を自動検査
6. 確認 5 点                            ← README.md 2 節
7. set NUGET_API_KEY=＜キー＞
   CS\NuGet\out\sp\_NuGetPush.bat
8. キーを Revoke（Delete しない）

バージョンを上げる

cd root\programs
.\0_SetVersion.ps1 -Version 3.3.0-alpha1 -WhatIf   # 変更内容の確認
.\0_SetVersion.ps1 -Version 3.3.0-alpha1           # 実行

Directory.Build.props と net48 6 本の AssemblyInfo.cs を一括更新する。 プレリリース サフィックスはアセンブリの版には入らない。 → RELEASE.md フェーズ 0

公開前の確認 5 点

→ CS/NuGet/README.md 2 節

1. .nupkg と .snupkg が対で出ている（.nupkg に pdb が入っていない）
2. PDB が portable（先頭 4 バイトが BSJB）
3. Source Link の URL が入っている（net48 と net10.0 の両方）
4. nuspec の <repository commit> が PDB のコミットと一致
5. そのコミットが GitHub 上にある（raw URL が 200）＋ ワーキング ツリーが綺麗

テスト公開（Erutcurtsarfni.Oyruot.Public）

CS\0_Release4Nuget.bat
CS\NuGet\_T_NuGetPack.bat 3.3.0-alpha2      ← 版は引数で渡す
set NUGET_API_KEY=＜キー＞
CS\NuGet\out\sp\_T_NuGetPush.bat

作業ブランチ上で行ってよい。→ CS/NuGet/README.md 4 節

生成物を消す

CS\NuGet\_Cleanup.bat                       ← in\ と out\ の全パッケージ
CS\NuGet\_Cleanup.bat Touryo.Infrastructure ← その接頭辞だけ

パック バッチが自動で呼ぶので、通常は不要。→ CS/NuGet/README.md 6 節

3. VB 側のビルドと疎通

cd root\programs
.\0_RunAll.ps1 -Lang VB       # 1 と 3 を VB で通す（2 は対象外）

.\1_BuildAll.ps1 -Lang VB     # 全ビルド（14 ステップ、4.3 分）
.\3_SmokeTest.ps1 -Lang VB    # 疎通（6 件、1.5 分）

従来の bat も使える。

root\programs\VB\0_ExecAllBat.bat           ← 通し（先に CS 側を建てる）
  • 先頭で cd "..\CS" して C# 側の 2_Build_NuGet_net48.bat を呼ぶ。VB は C# の成果物に依存する
  • 個別実行では見つからない不具合がある。 1_DeleteDir.bat が obj / packages を 消した後にだけ露見するものがあるため、通しで確かめること（#533）
  • 合格の目安 : ビルド 14/14 OK、疎通 6/6 OK
  • -IgnoreErrors は要らない（VB に ClickOnce 署名のプロジェクトが無い）
  • 単体テストは対象外（VB にテスト プロジェクトが無い）

VB のサンプルは nuget restore が要る。 しないと Microsoft.Data.SqlClient.SNI.x64.dll が出力に入らず、ビルドは通って実行時に落ちる。 BUILDING.md 10 節・SMOKETEST.md 10 節。

4. ツールを CLI で使う

引数の一覧は README に無い。/HELP が一次情報。

ツール 場所
DaoGen_Tool（墨壺） README.md
DeployZipPackWithHTTP README.md

終了コードだけで判断せず、生成物の存在も確認する（パス区切りを誤ると成功を返しつつ別の場所に出る）。

5. コードを書く前に

規約は CODING.md、領域ごとの事情は各 ANALYSIS.md。
ファイル ヘッダ・更新者名・Copyright ブロック CODING.md 1 節
ArgumentException だけ引数の順が違う CODING.md 3 節
フレームワーク本体 CS/Frameworks/ANALYSIS.md
net48 サンプル CS/Samples/ANALYSIS.md
netcore サンプル CS/Samples4NetCore/ANALYSIS.md

上の 3 つは俯瞰。アセンブリ・サンプルごとの下位の ANALYSIS.md は、各文書の冒頭の案内表から辿る（#613）。

.bat を書くとき

  • リリース・公開に使う bat は非 ASCII を書かない（コメントも英語）。BOM も不要
  • chcp を bat の中で使わない
  • 非 ASCII が外部プログラムへ渡す引数なら消せない。その場合は コンソールのコード ページに合わせる（Shift-JIS・BOM なし）
  • 改行は CRLF

→ CODING.md 4 節

.ps1 を書くとき

  • UTF-8 BOM 付き
  • PowerShell 5.1 と 7 の両方で動くこと。 変更したら 5.1 でも実行する
powershell.exe -NoProfile -Command "Set-Location 'root\programs'; .\3_SmokeTest.ps1"

→ CODING.md 5 節

6. よく踏む落とし穴

症状 原因 対処
'xxx' is not recognized が大量に出る bat の非 ASCII とコード ページ ASCII 化。CODING.md 4 節
MSB4226（Microsoft.WebApplication.targets） nuget が別製品の MSBuild を拾った nuget.exe restore ... %NUGET_MSBUILD%
ビルドは通るのに DllNotFoundException（...SNI...） nuget restore を呼んでおらず、ネイティブ DLL が出力に入らない 該当 sln に restore を足す。BUILDING.md 10 節
packages.config の id が csproj に無い＝不要に見える サテライト（.ja）とコンテンツ パッケージは出なくて正常（48 件中 44 件） 消す前に BUILDING.md 11 節
ビルドは通るのに実行時 FileNotFoundException 版は 4 か所に散らばる。 <Reference> の Version= がずれると、警告だけ出て参照が落ちる .\ComparePackage.ps1 -Check。BUILDING.md 12 節
MSB3021 / MSB3027（コピーできない・ロック）。error CS は 0 件 前回の疎通テストの残骸（中断されたときに残る）が出力を掴んでいる。疎通の「ポートが開かない」まで連鎖する 起動時刻で残存を見分けて停止。BUILDING.md 4 節

NuGet パッケージ作成の落とし穴は CS/NuGet/README.md 9 節にまとめてある。

.snupkg だけ 403 / F11 でローカルが開く / nuspec と PDB のコミット不一致
リビルド忘れ / net48 だけ効かない / 公開したコミットが消えた

上 5 つは公開前に机上で分かる。 2 節の確認 5 点を省かないこと。

7. エージェントとして守ること

一次情報は AGENTS.md。

  • Git 操作をしない（add / commit / push / checkout / switch / branch / reset / restore / stash）。参照系（status / diff / log / show 等）は自由
  • 状態を報告する直前に取り直す。 git status --porcelain / gh issue view / gh api。 前のターンの出力から書かない（人が独立にコミット・操作するため）
  • GitHub への投稿は、文面を提示して承認を得てから。 gh で行い、--body-file を使う。 アカウントは OsscJpDevInfra（gh auth status で確認）
  • Issue のクローズ・ラベル・アサイン、PR の作成やマージは人が行う
  • PR のレビューは --comment だけ。 --approve / --request-changes は人のみ
  • NuGet への push は人のみ（外部公開で取り消しが困難）
  • 前提となるサービスや DB の状態が足りないときは、勝手に変えず対処方法とともに報告する