Skip to content

CHEATSHEET.md

Latest commit

 

History

History
310 lines (227 loc) · 13.1 KB

CHEATSHEET.md

File metadata and controls

310 lines (227 loc) · 13.1 KB
Raw

チートシート

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

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

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
単体テスト 8/8 OK、差分 0 TESTING.md
疎通 30/30 OK SMOKETEST.md

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

  • 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）

.\3_SmokeTest.ps1 -List          # 対象名の一覧。-Lang が効く

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

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

基盤    NuGet / Business / Business.RichClient / CopyAssemblies
          ↓  （ここが変われば、下は全部やり直し）
末端    Tools / 各サンプル / Tests
変更した場所 1_BuildAll 2_RunAllTests 3_SmokeTest
Infrastructure/（基盤） 通し 通し 通し
Tools/（ツール） -Only Framework_Tool 不要 -Only <そのツール>
個別サンプル -Only <サンプル> 不要 -Only <サンプル>
Tests/ -Only <対象> -Only <対象> 不要
.ps1 / .md のみ 不要 不要 不要

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）

どちらもビルドの後に回す。 復元された 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

.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 節

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 の状態が足りないときは、勝手に変えず対処方法とともに報告する