Sorun giderme¶
Aşağıdaki her satır, bu şablon derlenirken gerçekten yaşanan bir şeydir -- tam mesaj (ya da sessiz bir başarısızlıksa, onun yerine ne göreceğiniz) ve depoya uygulanan veya sizin kendinizin uygulayacağı çözüm.
| Belirti / mesaj | Neden | Çözüm |
|---|---|---|
net7.0 projesi derleniyor ama .NET 7.0 is out of support uyarıları var, ya da yalnızca ilgisiz eski bir çalışma zamanı (runtime) kurulu olduğu için çalışıyor |
Hedef çerçeve (target framework), .NET 7 desteği bittiğinden beri (Mayıs 2024) güncellenmemiş | Bu şablonda düzeltildi: her .csproj, Directory.Build.props üzerinden net10.0'ı hedefliyor, global.json'da sabitlendi. Kendi çatalınızda (fork) görürseniz 4-install-tools'yı yeniden çalıştırın ve global.json'ı kontrol edin. |
Çözüm (solution) üzerinde dotnet publish, warning NETSDK1194: The "--output" option isn't supported when building a solution... yazdırır ve CalculatorLibrary, CalculatorApp, CalculatorLibrary.Tests çıktısını sessizce tek bir klasörde karıştırır |
-o ile bir .sln yayınlamak her projenin çıktısını aynı dizinde birleştirir -- güncel SDK'larda kesin bir hata değil, bu yüzden ikililer tuhaf davranana kadar fark edilmesi kolay değil |
Çözümü değil, uygulama projesini yayınlayın: dotnet publish CalculatorApp\CalculatorApp.csproj -c Release -r win-x64 -o publish\windows (10-release'in yaptığı tam olarak bu). |
reports/<platform>/_raw/doccoverage/lcov.info oluşuyor ama 0 bayt, hata yok, genhtml/ReportGenerator sonra "veri yok" gösteriyor |
coverxygen'in --prefix'i bir filtredir (yalnızca bu yolun altındaki dosyaları tut) ve orijinal scriptte %currentDir% hiç ayarlanmamış -- filtre hiçbir şeyle eşleşmemiş |
7-build-all, en başta currentDir/currentDirFwd'i ayarlar ve --prefix "%currentDirFwd%/" geçirir. |
Yukarıdaki satır, currentDir ayarlanacak şekilde düzeltildi ama Windows'ta hâlâ boş bir lcov.info üretiyor |
Doxygen, dosya yollarını içeride Windows'ta bile eğik çizgiyle (forward slash) kaydeder; --prefix, ters eğik çizgili (backslash) bir yolla karşılaştırılınca hiç eşleşmez |
Eğik çizgili bir prefix kullanın: set "currentDirFwd=%currentDir:\=/%", sonra --prefix "%currentDirFwd%/" (7-build-all.bat'te zaten yapılıyor; yolların doğal olarak eğik çizgili olduğu Linux'ta ilgisiz). |
Bir .bat scriptinde 'genhtml' is not recognized as an internal or external command, oysa where genhtml onu buluyor ve Git Bash'te doğrudan çalıştırmak işe yarıyor |
(Windows lcov Chocolatey paketinden) genhtml, .exe/.bat uzantısı olmayan bir Perl scriptidir; cmd.exe, uzantısız bir dosyayı doğrudan çalıştıramaz (shebang'ı okuyan bir POSIX kabuğunun aksine) |
Onu çıplak genhtml olarak değil, perl "<genhtml-yolu>" olarak çağırın -- 7-build-all.bat, yolu where genhtml ile çözer (yoksa varsayılan Chocolatey yoluna döner) ve her zaman perl üzerinden çalıştırır. |
pip install coverxygen başarılı olmasına rağmen python -m coverxygen, ModuleNotFoundError: No module named 'coverxygen' ile başarısız oluyor ve belge kapsama raporu sessizce boş |
Birden fazla Python kurulu bir makinede, PATH'teki düz python, coverxygen hiç kurulmamış ilgisiz bir yorumlayıcıya (ör. bir vektör grafik düzenleyicinin kendi paketlediği python.exe, gerçek bir Python'dan PATH'te daha önce bulunan) çözülebilir |
Açık bir yorumlayıcı kullanın: py -3.12 -m coverxygen ... (4-install-tools.bat/7-build-all.bat'in yaptığı); WSL/Linux'ta açıkça python3 kullanın. |
.gitignore, .csproj ya da kapsama sayıları kod nedeni olmadan her derlemede değişiyor |
Eski script her derlemede dotnet add package coverlet.msbuild çalıştırıyordu, CalculatorLibrary.Tests.csproj'u mutasyona uğratıp her seferinde sabitlenmemiş bir sürümü yeniden çözüyordu |
Kaldırıldı: kapsama, --collect:"XPlat Code Coverage" ile (zaten referans verilen coverlet.collector paketinden VSTest toplayıcısı) toplanır -- coverlet.msbuild bu toplama yöntemi tarafından hiç kullanılmıyordu ve artık hiç referans verilmiyor. Paket sürümleri doğrudan .csproj'da sabitlenir; bir derleme scriptinden asla dotnet add package çalıştırmayın. |
Bir xUnit [InlineData(new string[] { ... })] üzerinde error CS0182: An attribute argument must be a constant expression... |
Bir dizi değişmez değerini (array literal) doğrudan [InlineData]'ya geçiremezsiniz (özniteliğin kendi params object[]'i ile belirsiz) |
Bunun yerine statik bir IEnumerable<object[]> ile [MemberData(nameof(SomeMethod))] kullanın (bkz. CalculatorCliTests.WrongArgumentCounts). |
int.MinValue / -1 == int.MinValue doğrulayan bir test, kod hiçbir checked bloğu kullanmamasına rağmen bir değer döndürmek yerine System.OverflowException fırlatıyor |
Bu bir bölme, pozitif bir int olarak temsil edilemez (büyüklüğü int.MaxValue'dan bir fazladır); .NET, checked/unchecked bağlamından bağımsız olarak burada her zaman OverflowException fırlatır |
Bir dönüş değeri yerine istisnayı test edin: Assert.Throws<OverflowException>(() => calc.Divide(int.MinValue, -1)) (bkz. CalculatorTests). Bu, etrafından dolaşılacak bir hata değil, bilinmeye değer gerçek bir sınır durumudur. |
Etiket dosyada açıkça varken bir .bat scripti The system cannot find the batch label specified - <etiket> ile başarısız oluyor |
Dosyada Unix tarzı, yalnızca LF satır sonları var (ör. Windows dışı bir araçla düzenlendikten sonra); cmd.exe'nin GOTO/CALL :etiket araması, yalnızca-LF bir dosyada etiketi bulamayabilir |
CRLF'ye çevirin (ör. Git Bash'te: sed -i 's/\r$//' dosya.bat && sed -i 's/$/\r/' dosya.bat, ya da bir düzenleyicide: "Satır sonlarıyla kaydet: CRLF"). Bu depodaki her .bat CRLF'dir; öyle kalsın. |
Bir .bat scripti bir if (...)/for (...) bloğu içinde <bir kelime> was unexpected at this time. ile başarısız oluyor |
O blok içinde -- bir tırnaklı dizenin içinde olsa bile, bir yorum olarak olsa bile -- gerçek bir ( veya ) var ve bu, cmd.exe'nin blok sınırları için parantez eşleştirme taramasını karıştırıyor |
Bir parantezli blok içinde yaşayan hiçbir metinde gerçek parantez kullanmayın ("genhtml (documentation coverage)"i "genhtml - documentation coverage" olarak yeniden yazın vb.), ya da tırnak dışında ^(/^) ile kaçış karakteri (escape) kullanın. |
cd /d "%~dp0"'dan hemen sonra bile, dosya tam orada olmasına rağmen 'birsscript.bat' is not recognized as an internal or external command |
Makinede NoDefaultCurrentDirectoryInExePath ortam değişkeni ayarlı (yönetilen/laboratuvar bilgisayarlarında yaygın bir sertleştirme ayarı), bu da cmd.exe'nin çıplak dosya adları için örtük "geçerli dizini de ara" yedeğini devre dışı bırakır |
Kardeş scriptleri çıplak dosya adıyla değil, tam yolla çağırın: call scripts/dotnet-env-windows.bat değil, call "%~dp0scripts/dotnet-env-windows.bat" -- bu depodaki her script bunu zaten yapıyor. |
Bir .bat derleme adımı başarısız oluyor ama script mutlu bir şekilde bir sonraki adıma geçip yine de 0 koduyla çıkıyor |
call :etiket ile ulaşılan bir alt yordam (subroutine) içindeki exit /b 1, yalnızca o alt yordamı bitirir (bir return gibi), bütün scripti değil -- çağıran, sonucu açıkça kontrol etmelidir |
Her zaman call :check "adım adı" \|\| exit /b 1 olarak çağırın (ya da hemen ardından eşdeğer bir if errorlevel 1 exit /b 1), asla tek başına call :check "..." değil. |
Bir if (...)/for (...) bloğu içinde açıkça set edilmiş bir değişken, aynı blok içinde, hemen ardından boş (ya da eski) okunuyor |
cmd.exe, %degisken%'i her çalıştırmada değil, blok ayrıştırıldığında bir kez değiştirir -- aynı değişkenin aynı paylaşılan blok içinde önce set edilip sonra okunması, sessizce blok başlamadan önceki değeri kullanır |
Ya setlocal enabledelayedexpansion'ı etkinleştirip o okuma için !degisken! kullanın, ya da (bu şablonun mümkün olduğunda tercih ettiği gibi) set ile okumayı ayrı, üst düzey ifadelere bölün, böylece okuma, set zaten çalıştıktan sonra kendi taze ayrıştırılmış satırında gerçekleşir. |
Bir .bat scriptindeki robocopy adımı, kopyalama açıkça işe yaramış olsa bile başarısız sayılıyor |
robocopy'nin 0-7 çıkış kodlarının hepsi başarı/bilgilendirme niteliğindedir (1 = dosyalar kopyalandı, 2 = fazladan dosyalar, ...); yalnızca 8+ gerçek bir başarısızlıktır -- robocopy'den sonra düz bir if errorlevel 1 sürekli yanlış tetiklenir |
robocopy için özel olarak if errorlevel 1 değil if errorlevel 8 kontrol edin (7-build-all.bat'teki :check_robocopy'ye bakın). |
docfx build sırasında warning InvalidFileLink / Unable to find file "reports/....html" yazdırılıyor |
Bunlar kaynak (resource) dosyalarını (kopyalanan rapor HTML klasörlerini) işaret ediyor; DocFX'in TOC bağlantı doğrulayıcısı, bağlantıları kontrol ettiği noktada yalnızca içerik belgelerini izler, kaynak dosyaları değil | Zararsız: dosyalar yine de kopyalanır ve bağlantılar yine de çalışır (üretilen site açılarak doğrulandı). Bunun yerine gerçek içerik olması gereken bir .md dosyası için görürseniz docfx.json'ın content glob'larını/hariç tutmalarını (exclude) kontrol edin. |
Yepyeni bir .git\refs\heads\desktop.ini (veya benzeri) beliriyor ve git branch, warning: ignoring broken ref refs/heads/desktop.ini yazdırıyor |
Depo bir Google Drive senkronize klasörünün içinde yaşıyor ve Drive, kendi desktop.ini klasör-özelleştirme dosyasını .git'in içine yazıyor |
Zararsız; git bozuk referansı (ref) yok sayar. Bunu .git'i elle düzenleyerek "düzeltmeye" çalışmayın. |
Klon /mnt/g/My Drive/... altında yaşarken WSL depoyu göremiyor, ya da görüyor ama her dosya işlemi aşırı yavaş |
Google Drive for desktop sanal/bulut bir dosya sistemidir; G: sürücüsü üzerinden WSL'e bağlansa (mount) bile gerçek, tamamen POSIX-uyumlu bir dosya sistemi değildir |
Önce depoyu normal bir Linux yoluna kopyalayın (ör. ~/vs-net-core-template) ve her .sh scriptini oradan çalıştırın -- bu şablonun kendi .sh scriptleri tam olarak böyle test edildi (bkz. Her şeyi kurma). |
choco install astyle, bitirmek yerine bir [Y/n] onayı bekleyerek duruyor |
Bazı Chocolatey kurulum komutları, -y geçilmedikçe onay ister |
Düzeltildi: bu şablonun scriptlerindeki her choco install, -y geçiyor. Kendinizinkini eklerseniz aynısını yapın. |
| Numaralı bir script afişini yazdırıyor ve sonra terminale kontrolü hiç geri vermeden öylece oturuyor | Bir scriptin eski bir kopyası pause çağırıyordu (ya da başka türlü konsol girdisini bekliyordu) |
Bu şablondaki her script girdide bloklamaktan tamamen kaçınır (hiç pause yok). Örnek uygulama yalnızca kendi argümanlarını okur, konsolu asla okumaz, bkz. Konudan projeye. |
| Bir derleme adımı, özellikle antivirüs tanımlarını güncelledikten hemen sonra dosya-kilitli/"başka bir işlem tarafından kullanılıyor" hatasıyla başarısız oluyor | Windows Defender (veya başka bir antivirüs), yeni yazılan .dll/.exe dosyalarını tararken kısa süreliğine kilitler, bir sonraki derleme adımıyla yarışır |
Scripti yeniden çalıştırın (genelde yeterli); sürekli oluyorsa antivirüs ayarlarınızda depo klasörüne ve %LocalAppData%\Microsoft\dotnet'e bir istisna ekleyin. |
| Çok derin iç içe geçmiş bir klon konumunda, yol ile ilgili bir derleme hatası açıkça var olan bir dosyadan bahsediyor | Windows'un klasik ~260 karakter yol sınırı, uzun bir Google Drive yolu artı bin/obj artı uzun bir RID/yapılandırma alt klasörüyle daha kolay tetiklenir |
Bir sürücü köküne daha yakın klonlayın, ya da Windows uzun yol (long-path) desteğini etkinleştirin (git config --system core.longpaths true artı Windows 10/11'in "Win32 uzun yollarını etkinleştir" ayarı). |
site/index.html'i (veya bir raporu) bir file:// yolu üzerinden açmak boş bir sayfa ya da kırık bağlantılar gösteriyor ama HTTP üzerinden sunulunca çalışıyor |
Nadir, ama bazı tarayıcılar file:// sayfalarının bitişik JSON getirmesini kısıtlar (ör. DocFX'in arama indeksi) |
Bunun yerine yerelde sunun: 9-open-site.bat/.sh (artık bunu otomatik yapıyor), dotnet docfx serve site (varsayılan http://localhost:8080), ya da herhangi bir statik dosya sunucusu. |
Bir rapor sayfasının <iframe>'i boş kalıyor, oysa aynı sayfadaki "Yeni sekmede aç" çalışıyor |
Site, 9-open-site'nin yerel sunucusu yerine çıplak bir file:// yolu üzerinden açıldı -- tam açıklama ve diğer bütün iframe sorunları için bkz. Sitenizin içinde bir raporu göstermek |
9-open-site.bat/.sh'yi kullanın ve yazdırılan http://localhost:8080/ URL'sini açın. |
9-open-site.bat/.sh, siteyi sunmak yerine bir hatayla çıkıyor |
8080 portu (varsayılan) makinenizde başka bir şey tarafından zaten kullanılıyor | Farklı bir port verin: 9-open-site.bat 8081 / ./9-open-site.sh 8081. |
Compress-Archive (7-build-all.bat'in rapor-zipleme adımında) dosya-kullanımda hatasıyla başarısız oluyor |
Script yeniden çalışırken bir raporun HTML dosyası hâlâ bir tarayıcıda/editörde açıktı, ya da antivirüs onu yazılırken tarıyordu (yukarıdaki antivirüs satırına bakın) | docs/<rapor>/ altında açık bir dosyası olan her şeyi kapatın, sonra 7-build-all.bat'i yeniden çalıştırın; adım yeniden çalıştırılabilir (idempotent). |
Hâlâ takıldınız mı?¶
Günlük iş akışı veya Şablonu kullanma'daki tam
adımı yeniden okuyun, doğru dosyaya baktığınızdan emin olmak için
Hangi rapor hangisi?'i kontrol edin.
| MSB4126: The specified solution configuration "Debug|windows" is invalid | MSBuild, PLATFORM ortam değişkenini Platform özelliği olarak okur; PLATFORM=windows dışa aktaran bir betik her derlemeyi bozar | Betikler bunun yerine PLATFORM_TOKEN kullanır; PLATFORM adlı bir değişken dışa aktarmayın |
| mkdocs / ModuleNotFoundError: No module named 'material' | MkDocs Material o Python için kurulu değil | 4-install-tools-<platform> (veya py -3.12 -m pip install --user -r requirements.txt) |
| check-links broken link(s) yazdırıyor | Bir sayfa eksik bir şeye bağlanıyor (yazım hatası ya da kopyalanmamış rapor klasörü) | Yazdırdığı yolu düzeltin; bkz. Sitenizin içinde HTML raporu göstermek "Sık sorunlar" |
| Bir rapor sayfasında "bu makinede üretilmedi" yazıyor | Yalnız bir platformda derlediniz; diğer platformun raporları orada üretilir (CI ikisini de üretir) | O platformda 7-build-all çalıştırın veya sürümü kullanın |
| dotnet build sonrası dotnet test dll'yi bulamıyor | Derleme ve test farklı --artifacts-path kullandı | Numaralı betikleri kullanın; ikisine de build/<platform>-<config> verirler |
| 9-open-site 8080 portunun kullanımda olduğunu söylüyor | Başka bir program orayı dinliyor | 9-open-site-windows.bat 8081 (veya ./9-open-site-linux.sh 8081) |