Paket Kimliği ile Hata Ayıklama

Birçok Windows API'si (anında iletme bildirimleri, arka plan görevleri, hedefi paylaşma, başlangıç görevleri Windows yapay zeka API'leri) uygulamanızın package identity sahip olmasını gerektirir. Geliştirme sırasında, her testinizde tam bir MSIX yükleyicisi oluşturmak istemezsiniz; winapp, uygulama kimliğinizi anında vermek için iki komut sağlar.

Paketleme projesiyle Visual Studio mi kullanıyorsunuz? Paketlenmiş projeniz için zaten Visual Studio kullanıyorsanız hata ayıklama için winapp'e ihtiyacınız yoktur. Visual Studio zaten paket kaydını, kimliği, AUMID etkinleştirmesini, hata ayıklayıcı eklemesini ve etkinleştirme kodu hata ayıklamasını F5 ile işler. Ayrıca gelişmiş senaryolar için Hata Ayıklama → Diğer Hata Ayıklama Hedefleri → Yüklü Uygulama Paketinde Hata Ayıklama sunar. Aşağıdaki iş akışları VS Code kullanıcıları, terminal tabanlı iş akışları ve VS'nin yerel olarak paketlemediği çerçeveler (Rust, Flutter, Tauri, Electron, plain C++) için en kullanışlıdır.

İki yaklaşım: `winapp run` vs `create-debug-identity`

	`winapp run`	`create-debug-identity`
Ne kaydeder	Tam gevşek düzen paketi (klasörün tamamı)	Hafif paket (tekli exe)
Uygulama nasıl başlatılır?	winapp tarafından başlatıldı (AUMID'nin etkinleştirilmesi veya yürütme takma adı)	Exe'yi kendiniz başlatırsınız (komut satırı, IDE vb.)
MSIX yüklemesini simüle eder	Evet — üretim davranışına en yakın	Hayır — yalnızca seyrek kimlik
Dosyalar yerinde kalır	AppX düzen dizinine kopyalandı	Evet — exe özgün yolunda kalıyor
Kimlik kapsamı	Tüm klasör içeriği (exe, DLL'ler, varlıklar)	Tek yürütülebilir dosya
Hata ayıklayıcı dostu	Başlatıldıktan sonra PID'ye bağlanma veya alias kullanarak başlatma `--no-launch`	Doğrudan IDE'nizin hata ayıklayıcısından başlatın; exe her durumda kimliğini korur.
Konsol uygulaması desteği	`--with-alias` stdin/stdout'un terminalde kalmasını sağlar	Exe'yi doğrudan terminalde çalıştırma
En uygun	Çoğu çerçeve (.NET, C++, Rust, Flutter, Tauri)	Elektron veya tam IDE hata ayıklayıcısı denetimine ihtiyacınız olduğunda (F5)

Ne zaman kullanılır?

Varsayılan: `winapp run`

Çoğu geliştirme iş akışı için kullanın winapp run . Gerçek bir MSIX yüklemesinin benzetimini yapar; uygulamanız üretimde sahip olduğu kimlik, yetenek ve dosya ilişkilendirmeleriyle aynı olur.

# Build your app, then:
winapp run .\build\output

Şu durumlarda kullanın `create-debug-identity` :

Exe'niz derleme çıkışınızdan ayrıdır — örneğin, node_modules/ içinde yaşayan electron.exe Electron uygulamaları
Başlangıç kodunda hata ayıklamanız gerekiyor ve AUMID başlatıldıktan sonra yeterince hızlı bir hata ayıklayıcı ekleyemezsiniz
AUMID ile başlatılamayan ve başlatılan süreçte kimliğe ihtiyaç duyulan bazı hata ayıklayıcılar ile, create-debug-identity exe dosyasını kaydeder, böylece her başlatıldığında kimliğe sahip olur
Seyrek paket davranışını özel olarak test ediyorsun (AllowExternalContent, TrustedLaunch)

# Register identity for an exe, then launch it however you want:
winapp create-debug-identity .\bin\Debug\myapp.exe
.\bin\Debug\myapp.exe   # or F5 in your IDE

Hata ayıklama senaryoları

Senaryo A: Sadece kimlikle çalıştır

En basit iş akışı: derleme, kimlikle çalıştırma, bitti.

winapp run .\build\Debug

Winapp klasörü gevşek bir düzen paketi olarak kaydeder ve uygulamayı başlatır. Kimlik gerektiren API'ler hemen çalışır. Bu, geliştirme ve test senaryolarının çoğunu kapsar.

Geçerli terminalde stdin/stdout gerektiren konsol uygulamaları için ekleyin --with-alias:

winapp run .\build\Debug --with-alias

Senaryo B: Çalışan bir uygulamaya hata ayıklayıcı ekleme

ile winapp runbaşlatın, PID'yi not edin ve ardından IDE'nizin hata ayıklayıcısını ekleyin.

winapp run .\build\Debug
# Output: Process ID: 12345

Ardından IDE'nizde:

VS Code: Çalıştırma ve Hata Ayıklama → "Ekle" yapılandırmasını seçin (aşağıdaki IDE kurulumuna bakın)
WinDbg: windbg -p 12345

Sınırlama: Bağlamadan önce çalıştırılan tüm kodları kaçıracaksınız. Başlangıç hata ayıklaması için Senaryo D (create-debug-identity) kullanın.

Senaryo C: Kimliği kaydedin, ardından IDE'nizden AUMID veya diğer ad aracılığıyla başlatın

Paketi kaydetmek için --no-launch kullanarak, ardından uygulamayı run tarafından bildirilen AUMID veya IDE'nizden yürütme takma adı aracılığıyla başlatın.

1. Adım: Paketi başlatmadan kaydedin:

winapp run .\build\Debug --no-launch

2. Adım: IDE'nizi AUMID veya yürütme diğer adı (doğrudan exe değil) aracılığıyla başlatacak şekilde yapılandırın.

AUMID ile başlatma: komutunu start shell:AppsFolder\<AUMID>kullanın. winapp run uygulama kaydedildiğinde AUMID'yi çıkış olarak verir.
Diğer adla başlatma: Diğer ad bildiriminizde tanımlanmalıdır (Package.appxmanifest tercih edilir, appxmanifest.xml ayrıca desteklenir).

Önemli: Exe dosyasını derleme klasöründe başlatmak, bu klasöre kimlik vermez. Uygulamanın AUMID etkinleştirmesi veya çalıştırma takma adı aracılığıyla başlatılması gerekir. Gevşek düzen paketleri bu şekilde çalışır. Kimlik, exe dosyasına değil etkinleştirme yoluna bağlıdır.

Senaryo D: Kimlik bilgileriyle IDE'den başlatma (başlatma sırasında hata ayıklama)

Bu, tam IDE denetimiyle başlangıç kodunda hata ayıklamak için en iyi yaklaşımdır. IDE'nizin hata ayıklayıcısı başlangıçtan itibaren işlemi denetler ve exe, nasıl başlatılırsa başlatılsın kimliğini korur.

winapp create-debug-identity .\build\Debug\myapp.exe

Şimdi exe dosyasını istediğiniz gibi başlatın; terminalden, VS Code'un F5'inden, bir betikten. EXE dosyası, Windows'un doğrudan ona işaret eden bir sparse paketi kaydetmiş olması nedeniyle kimlik bilgisine sahiptir.

winapp run ile nasıl farklıdır:create-debug-identity ile, kimlik exe'nin kendisine bağlıdır (c3 /> aracılığıyla). winapp run ile kimlik, serbest düzen paketine bağlıdır; uygulama AUMID veya bir takma ad aracılığıyla başlatılmalıdır. Bu, IDE'nizin exe'yi doğrudan başlatıp hatalarını ayıklamasına ihtiyacınız olduğunda create-debug-identity daha iyi bir seçim yapar.

Bu ayrıca, exe yolunun kaynak dizininizden farklı olduğu Electron uygulamaları için de en iyi yaklaşımdır.

Senaryo E: Hata ayıklama çıkışını ve çökme teşhislerini yakalama

İletileri ve ilk şans özel durumlarını satır içinde yakalayın OutputDebugString . Çerçeve gürültüsü (WinUI, COM, DirectX iç izlemeleri) konsolundan filtrelenir, böylece yalnızca uygulamanızın hata ayıklama iletileri görüntülenir. Her şey hala tam araştırma için log dosyasına yazılmaktadır.

Uygulama kilitlenirse, bir minidump otomatik olarak yakalanır ve analiz edilir.

winapp run .\build\Debug --debug-output

Çökme sırasında, kaynak dosya ve satır numaralarıyla (derleme çıktı klasörünüzdeki PDB'lerden çözümlenen) hata türünü, iletiyi ve hata izlemesini içeren bir çıktı üretilir. Yönetilen (.NET) kilitlenmeler harici araçlar olmadan anında analiz edilir. Yerel (C++/WinRT) kilitlenmeleri modül adlarını ve offset'lerini gösterir; tam işlev adları için PDB sembollerini indirmek amacıyla --symbols ekleyin.

winapp run .\build\Debug --debug-output --symbols

Önemli: Bu işlem winapp'i hata ayıklayıcısı olarak ekler. Windows işlem başına yalnızca bir hata ayıklayıcıya izin verir, bu nedenle Visual Studio, VS Code veya WinDbg bağlayamazsınız.

IDE kurulumu

VS Code

WinApp VS Code uzantısı, uygulamanızı paket kimliğiyle başlatan ve tek bir winapp basımından hata ayıklayıcısını ekleyen özel bir hata ayıklama türü sağlar.

Kimlik doğrulamayı kullanarak tek tuşla F5 hata ayıklaması

winapp başlatma yapılandırmasını .vscode/launch.json içerisine ekleyin:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "winapp",
            "request": "launch",
            "name": "WinApp: Launch and Attach"
        }
    ]
}

F5 tuşuna bastığınızda:

Uzantı, .exe dosyalarını içeren derleme çıktısı dizinleri için çalışma alanınızı tarar.
Çalıştırmak için derleme klasörünü seçersiniz (veya istemi atlamak için inputFolder ayarlarsınız).
winapp run aracılığıyla uygulamanıza paket kimliği vermek için başlatır.
Çocuk hata ayıklama oturumu, belirttiğiniz hata ayıklayıcıyı kullanarak çalışan işleme eklenir.

Hata ayıklayıcı eklendikten sonra tam VS Code hata ayıklama deneyimini elde edersiniz. Bölme çubuğuna tıklayarak kesme noktaları ayarlayın, kodda satır satır ilerleyin (F10 ), işlevlere adımlayın (F11 ), Değişkenler bölmesinde değişkenleri inceleyin ve Hata Ayıklama Konsolu'ndaki ifadeleri değerlendirin. Uygulama boyunca paket kimliğiyle çalıştığından, kimliğe bağımlı API'ler üretimde olduğu gibi davranır.

Önemli: Hata winapp ayıklama türü projenizi otomatik olarak oluşturmaz . Kod değişiklikleri yaptıktan sonra F5 tuşuna basmadan önce yeniden oluşturun.

Derlemeleri `preLaunchTask` ile otomatikleştirin

Yeniden derlemeyi unutmamak için, her hata ayıklama oturumundan önce projenizi oluşturan bir preLaunchTask ekleyin:

.vscode/tasks.json içinde bir derleme görevi tanımlama (.NET örneği):

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build", "${workspaceFolder}"],
            "problemMatcher": "$msCompile"
        }
    ]
}

Bunu launch.json içinde belirtin.

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch and Attach",
    "preLaunchTask": "build"
}

Yapılandırma özellikleri

Mülkiyet	Türü	Varsayılan	Description
`inputFolder`	string		Uygulama ikili dosyalarınızı içeren derleme çıkış klasörünün yolu (ör. `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`). Ayarlanmamışsa, bir klasör seçmeniz istenir.
`manifest`	string		AppX bildirim dosyasının yolu (ör. , `AppxManifest.xmlPackage.appxmanifest`veya `appxmanifest.xml`). Ayarlanmazsa, CLI giriş klasöründen veya geçerli dizinden otomatik olarak algılar.
`debuggerType`	string	`coreclr`	(`coreclr`, `cppvsdbg`veya `node`) kullanılacak temel hata ayıklayıcı
`workingDirectory`	string	çalışma alanı klasörü	Uygulama için çalışma dizini.
`args`	string		Uygulamaya geçirmek için komut satırı bağımsız değişkenleri.
`outputAppxDirectory`	string		Gevşek düzen paketi için çıkış dizini. Giriş klasörünün içindeki bir `AppX` klasörü varsayılan olarak kullanır.
`port`	number	`9229`	(`node` yalnızca) Node.js `--inspect` dinleyicisi ve bağlama bağlantısı için kullanılan port. Varsayılan bağlantı noktası zaten kullanımda olduğunda geçersiz kılın.

Desteklenen hata ayıklayıcıları

`debuggerType`	Language	Gerekli Uzantı
`coreclr` (varsayılan)	C# / .NET	C# Geliştirme Seti
`cppvsdbg`	C / C++	C/C++
`node`	Node.js / Elektron	Dahili

C++ projesi örneği:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}

Hata Ayıklama Kimliği Oluştur ile hata ayıklamayı başlatma

Başlangıç kodunda ilk yönergeden itibaren hata ayıklamanız gerekiyorsa, F5 ile ekleme yöntemi erken kodu kaçırabilir. Bunun yerine, yürütülebilir dosyanız için seyrek bir paket kaydetmek için Komut Paleti'nden () Ctrl+Shift+P komutunu kullanın ve ardından standart hata ayıklayıcınızla başlatın:

{
    "name": "Launch (with identity)",
    "type": "coreclr",
    "request": "launch",
    "program": "${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621/myapp.exe"
}

Kimlik, exe'ye doğrudan kaydedildiğinden, standart VS Code başlatma yapılandırması da dahil olmak üzere, uygulama nasıl başlatılırsa başlatılsın kimliğe sahiptir.

Çalışan işleme ekleme

ile terminalden başlatmayı winapp run ve ardından eklemeyi tercih ediyorsanız standart bir ekleme yapılandırması kullanın:

{
    "name": "Attach to Process",
    "type": "coreclr",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

C++/Rust için (MSVC) veya "type": "cppvsdbg" (LLDB) kullanın "type": "lldb" :

{
    "name": "Attach (C++)",
    "type": "cppvsdbg",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Temizleme

Testi tamamladığınızda, VS Code'dan çıkmadan dışarıdan yüklenen geliştirme paketlerini kaldırmak için Komut Paletinden WinApp: Paketin Kaydını Sil'i çalıştırın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-05-12