Aracılığıyla paylaş

Windows PowerShell Hata Kayıtları

Cmdlet'ler, sonlandırıcı ve sonlandırılmayan hataların hata koşulunu tanımlayan bir System.Management.Automation.ErrorRecord nesnesi geçirmelidir.

System.Management.Automation.ErrorRecord nesnesi aşağıdaki bilgileri içerir:

  • Hatayı açıklayan özel durum. Genellikle bu, cmdlet'in yakalanıp hata kaydına dönüştürüldüğü bir özel durumdur. Her hata kaydı bir özel durum içermelidir.

Cmdlet bir özel durum yakalamadıysa, yeni bir özel durum oluşturmalı ve hata koşulunu en iyi açıklayan özel durum sınıfını seçmelidir. Ancak, System.Management.Automation.ErrorRecord.Exception System.Management.Automation.ErrorRecord nesnesi aracılığıyla erişilebildiği için özel durum oluşturmanız gerekmez.

  • Tanılama amacıyla ve Windows PowerShell betikleri tarafından belirli hata işleyicileriyle belirli hata koşullarını işlemek için kullanılabilecek hedefli bir belirleyici sağlayan hata tanımlayıcısı. Her hata kaydı bir hata tanımlayıcısı içermelidir (bkz. Hata Tanımlayıcısı).

  • Tanılama amacıyla kullanılabilecek genel bir belirleyici sağlayan bir hata kategorisi. Her hata kaydı bir hata kategorisi belirtmelidir (bkz. Hata Kategorisi).

  • İsteğe bağlı bir değiştirme hata iletisi ve önerilen bir eylem (bkz. Değiştirme Hata İletisi).

  • Hatayı oluşturan cmdlet hakkında isteğe bağlı çağırma bilgileri. Bu bilgiler Windows PowerShell tarafından belirtilir (bkz. Çağırma İletisi).

  • Hata oluştuğunda işlenen hedef nesne. Bu giriş nesnesi veya cmdlet'inizin işlemekte olduğu başka bir nesne olabilir. Örneğin, Remove-Item -Recurse C:\somedirectorykomutu için hata , "C:\somedirectory\lockedfile" için fileInfo nesnesinin bir örneği olabilir. Hedef nesne bilgileri isteğe bağlıdır.

Hata Tanımlayıcısı

Bir hata kaydı oluşturduğunuzda, cmdlet'inizde hata koşulunu belirten bir tanımlayıcı belirtin. Windows PowerShell, tam hata tanımlayıcısı oluşturmak için hedeflenen tanımlayıcıyı cmdlet'inizin adıyla birleştirir. Tam hata tanımlayıcıya, System.Management.Automation.ErrorRecord nesnesinin System.Management.Automation.ErrorRecord.FullyQualifiedErrorId özelliği aracılığıyla erişilebilir. Hata tanımlayıcısı tek başına kullanılamaz. Yalnızca tam hata tanımlayıcısının bir parçası olarak kullanılabilir.

Hata kayıtları oluştururken hata tanımlayıcıları oluşturmak için aşağıdaki yönergeleri kullanın:

  • Hata tanımlayıcılarını bir hata koşuluna özgü hale getirin. Tanılama amacıyla ve belirli hata işleyicileri olan belirli hata koşullarını işleyen betikler için hata tanımlayıcılarını hedef alın. Bir kullanıcı, hatayı ve kaynağını tanımlamak için hata tanımlayıcısını kullanabilmelidir. Hata tanımlayıcıları, yeni özel durum alt sınıflarının gerekli olmaması için mevcut özel durumlardan belirli hata koşulları için raporlamayı da etkinleştirir.

  • Genel olarak, farklı kod yollarına farklı hata tanımlayıcıları atayın. Son kullanıcı belirli tanımlayıcılardan yararlanır. Genellikle, System.Management.Automation.Cmdlet.WriteError veya System.Management.Automation.Cmdlet.ThrowTerminatingError* çağıran her kod yolunun kendi tanımlayıcısı vardır. Kural olarak, hata iletisi için yeni bir şablon dizesi tanımlarken (veya tam tersi) yeni bir tanımlayıcı tanımlayın. Hata iletisini tanımlayıcı olarak kullanmayın.

  • Belirli bir hata tanımlayıcısını kullanarak kod yayımladığınızda, tüm ürün destek yaşam döngünüz için bu tanımlayıcıyla hataların semantiğini oluşturursunuz. Özgün bağlamdan farklı bir bağlamda yeniden kullanmayın. Bu hatanın semantiği değişirse yeni bir tanımlayıcı oluşturun ve kullanın.

  • Genellikle belirli bir hata tanımlayıcısını yalnızca belirli bir CLR türü özel durumları için kullanmanız gerekir. Özel durumun türü veya hedef nesnenin türü değişirse, yeni bir tanımlayıcı oluşturun ve kullanın.

  • Hata tanımlayıcınız için, bildirdiğiniz hataya kısa bir şekilde karşılık gelen metni seçin. Standart .NET Framework adlandırma ve büyük harfe çevirme kurallarını kullanın. Boşluk veya noktalama işaretleri kullanmayın. Hata tanımlayıcılarını yerelleştirmeyin.

  • Yeniden üretilemeyen bir şekilde dinamik olarak hata tanımlayıcıları oluşturmayın. Örneğin, işlem kimliği gibi hata bilgilerini birleştirmeyin. Hata tanımlayıcıları yalnızca aynı hata koşuluyla karşılaşan diğer kullanıcılar tarafından görülen hata tanımlayıcılarına karşılık geliyorsa kullanışlıdır.

Hata Kategorisi

Hata kaydı oluşturduğunuzda, System.Management.Automation.ErrorCategory sabit listesi tarafından tanımlanan sabitlerden birini kullanarak hata kategorisini belirtin. Windows PowerShell, kullanıcılar $ErrorView değişkenini "CategoryView"olarak ayarladığında hata bilgilerini görüntülemek için hata kategorisini kullanır.

System.Management.Automation.ErrorCategoryNotSpecified sabitini kullanmaktan kaçının. Hata veya hataya neden olan işlem hakkında herhangi bir bilginiz varsa, kategori mükemmel eşleşme olmasa bile hatayı veya işlemi en iyi açıklayan kategoriyi seçin.

Windows PowerShell tarafından görüntülenen bilgiler kategori görünümü dizesi olarak adlandırılır ve System.Management.Automation.ErrorCategoryInfo sınıfının özelliklerinden oluşturulur. (Bu sınıfa System.Management.Automation.ErrorRecord.CategoryInfo özelliği hatasıyla erişilir.)

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

Aşağıdaki listede görüntülenen bilgiler açıklanmaktadır:

  • Kategori: Windows PowerShell tanımlı System.Management.Automation.ErrorCategory sabiti.

  • TargetName: Varsayılan olarak, hata oluştuğunda cmdlet'in işlemekte olduğu nesnenin adıdır. Veya başka bir cmdlet tanımlı dize.

  • TargetType: Varsayılan olarak hedef nesnenin türü. Veya başka bir cmdlet tanımlı dize.

  • Etkinlik: Varsayılan olarak, hata kaydını oluşturan cmdlet'in adıdır. Veya başka bir cmdlet tanımlı dize.

  • Neden: Varsayılan olarak özel durum türü. Veya başka bir cmdlet tanımlı dize.

Değiştirme Hata İletisi

Bir cmdlet için hata kaydı geliştirirken, hatanın varsayılan hata iletisi System.Exception.Message özelliğindeki varsayılan ileti metninden gelir. Bu, ileti metni yalnızca hata ayıklama amacıyla (.NET Framework yönergelerine göre) amaçlanan salt okunur bir özelliktir. Varsayılan ileti metninin yerini alan veya genişleten bir hata iletisi oluşturmanızı öneririz. İletiyi daha kullanıcı dostu ve cmdlet'e daha özel hale getirin.

Değiştirme iletisi bir System.Management.Automation.ErrorDetails nesnesi tarafından sağlanır. Windows PowerShell tarafından kullanılabilecek ek yerelleştirme bilgileri sağladığından, bu nesnenin aşağıdaki oluşturucularından birini kullanın.

Değiştirme iletisi, küçük bir farkla özel durum iletileri yazmak için .NET Framework tasarım yönergelerine uygun olmalıdır. Yönergeler, özel durum iletilerinin geliştiriciler için yazılması gerektiğini belirtir. Bu değiştirme iletileri cmdlet kullanıcısı için yazılmalıdır.

System.Management.Automation.Cmdlet.WriteError veya System.Management.Automation.Cmdlet.ThrowTerminatingError* yöntemleri çağrılmadan önce değiştirme hata iletisi eklenmelidir. Değiştirme iletisi eklemek için, hata kaydının System.Management.Automation.ErrorRecord.ErrorDetails özelliğini ayarlayın. Bu özellik ayarlandığında, Windows PowerShell varsayılan ileti metni yerine System.Management.Automation.ErrorDetails.Message* özelliğini görüntüler.

System.Management.Automation.ErrorDetails nesnesi, hata oluştuğunda hangi eylemlerin önerlendiği hakkında da bilgi sağlayabilir.

Çağırma bilgileri

Bir cmdlet bir hata kaydını bildirmek için System.Management.Automation.Cmdlet.WriteError veya System.Management.Automation.Cmdlet.ThrowTerminatingError* kullandığında, Windows PowerShell hata oluştuğunda çağrılan komutu açıklayan bilgileri otomatik olarak ekler. Bu bilgiler, komut tarafından çağrılan cmdlet'in adını, komutun kendisini ve işlem hattı veya betik hakkındaki bilgileri içeren bir System.Management.Automation.InvocationInfo nesnesi tarafından sağlanır. Bu özellik salt okunurdur.

Ayrıca Bkz.

System.Management.Automation.Cmdlet.WriteError

System.Management.Automation.Cmdlet.ThrowTerminatingError*

System.Management.Automation.ErrorCategory

System.Management.Automation.ErrorCategoryInfo

System.Management.Automation.ErrorRecord

System.Management.Automation.ErrorDetails

System.Management.Automation.InvocationInfo

Windows PowerShell Hata Raporlama

Windows PowerShell Cmdlet'i yazma

  • Last updated on