Windows PowerShell Hata Kayıtları

Cmdlet'lerin, sonlandırılan ve sonlandırılmayan hatalar için hata koşulunu tanımlayan bir System.Management.Automation.ErrorRecord nesnesini iletmesi gerekir.

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

  • Hatayı açıklayan istisna. Çoğu zaman bu, cmdlet'in yakalayıp bir hata kaydına dönüştürdüğü bir istisnadır. Her hata kaydının bir istisna içermesi gerekir.

Cmdlet bir istisna yakalayamadıysa yeni bir istisna oluşturmalı ve hata durumunu en iyi açıklayan istisna sınıfını seçmelidir. Ancak, System.Management.Automation.ErrorRecord.Exception nesnesinin System.Management.Automation.ErrorRecord özelliği aracılığıyla erişilebildiği için istisnayı oluşturmanıza gerek yoktur.

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

  • Tanılama amacıyla kullanılabilecek genel bir tanımlayıcı sağlayan bir hata kategorisi. Her hata kaydında bir hata kategorisi belirtilmelidir (bkz. Hata Kategorisi).

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

  • Hatayı oluşturan cmdlet'e ilişkin isteğe bağlı çağırma bilgileri. Bu bilgiler Windows PowerShell tarafından belirtilir (bkz. Çağrı Mesajı).

  • Hata oluştuğunda işlenmekte olan hedef nesne. Bu giriş nesnesi olabilir veya cmdlet'inizin işlediği başka bir nesne olabilir. Örneğin, remove-item -recurse c:\somedirectory komutu için hata, "c:\somedirectory\lockedfile" için bir FileInfo nesnesi örneği olabilir. Hedef nesne bilgisi isteğe bağlıdır.

Hata Tanımlayıcı

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

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

  • Bir hata durumuna özel hata tanımlayıcıları yapın. Tanılama amacıyla ve belirli hata işleyicileriyle belirli hata koşullarını işleyen komut dosyaları için hata tanımlayıcılarını hedefleyin. Kullanıcı, hatayı ve kaynağını tanımlamak için hata tanımlayıcıyı kullanabilmelidir. Hata tanımlayıcıları ayrıca mevcut istisnalardan belirli hata koşullarının raporlanmasını da mümkün kılar, böylece yeni istisna alt sınıflarına gerek kalmaz.

  • Genel olarak farklı kod yollarına farklı hata tanımlayıcıları atayın. Son kullanıcı belirli tanımlayıcılardan yararlanır. Çoğunlukla, System.Management.Automation.Cmdlet.WriteError veya System.Management.Automation.Cmdlet.Throwtertainederror*'ı çağıran her kod yolunun kendi tanımlayıcısı vardır. Kural olarak, hata mesajı için yeni bir şablon dizesi tanımladığınızda yeni bir tanımlayıcı tanımlayın veya bunun tersi de geçerlidir. Hata mesajını tanımlayıcı olarak kullanmayın.

  • Belirli bir hata tanımlayıcıyı kullanarak kod yayınladığınızda, ürün destek yaşam döngünüzün tamamı için bu tanımlayıcıyla hataların semantiğini oluşturursunuz. Orijinal bağlamdan anlamsal olarak farklı bir bağlamda yeniden kullanmayın. Bu hatanın anlamı değişirse yeni bir tanımlayıcı oluşturup kullanın.

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

  • Hata tanımlayıcınız için, bildirdiğiniz hataya tam olarak karşılık gelen metni seçin. Standart .NET Framework adlandırma ve büyük harf kullanım kurallarını kullanın. Beyaz boşluk veya noktalama işareti kullanmayın. Hata tanımlayıcılarını yerelleştirmeyin.

  • Hata tanımlayıcılarını tekrarlanamayacak şekilde dinamik olarak oluşturmayın. Örneğin, işlem kimliği gibi hata bilgilerini dahil etmeyin. Hata tanımlayıcıları yalnızca aynı hata durumunu yaşayan diğer kullanıcılar tarafından görülen hata tanımlayıcılarına karşılık gelmeleri durumunda kullanışlıdır.

Hata Kategorisi

Bir hata kaydı oluşturduğunuzda, System.Management.Automation.ErrorCategory numaralandırması tarafından tanımlanan sabitlerden birini kullanarak hatanın 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.ErrorCategory NotSpecified sabitini kullanmaktan kaçının. Hata veya hataya neden olan işlem hakkında herhangi bir bilginiz varsa, kategori mükemmel bir eşleşme olmasa bile hatayı veya işlemi en iyi açıklayan kategoriyi seçin.

Windows PowerShell tarafından görüntülenen bilgilere kategori görünümü dizesi adı verilir ve System.Management.Automation.Errorcategoryinfo sınıfının özelliklerinden oluşturulur. (Bu sınıfa System.Management.Automation.ErrorRecord.CategoryInfo özelliği aracılığı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şlediği nesnenin adı. 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ı. Veya başka bir cmdlet tanımlı dize.

  • Sebep: Varsayılan olarak istisna türü. Veya başka bir cmdlet tanımlı dize.

Değiştirme Hata Mesajı

Bir cmdlet için bir hata kaydı geliştirdiğinizde, hataya ilişkin varsayılan hata iletisi System.Exception.Message özelliğindeki varsayılan ileti metninden gelir. Bu, mesaj metni yalnızca hata ayıklama amacıyla tasarlanan salt okunur bir özelliktir (.NET Framework yönergelerine göre). Varsayılan mesaj metninin yerine geçen veya onu tamamlayan bir hata mesajı oluşturmanızı öneririz. Mesajı daha kullanıcı dostu ve cmdlet'e daha spesifik hale getirin.

Değiştirme mesajı bir System.Management.Automation.ErrorDetails nesnesi tarafından sağlanır. Bu nesnenin aşağıdaki oluşturucularından birini kullanın çünkü bunlar, Windows PowerShell tarafından kullanılabilecek ek yerelleştirme bilgileri sağlar.

  • ErrorDetails(Cmdlet, String, String, Object[]): Şablon dizeniz, cmdlet'in uygulandığı aynı derlemedeki bir kaynak dizesiyse veya şablon dizesini System. Management.Automation.Cmdlet.GetResourceString yöntemi.

  • ErrorDetails(Assembly, String, String, Object[]): Şablon dizesi başka bir derlemedeyse ve bunu System.Management.Automation.Cmdlet.GetResourceString geçersiz kılma yoluyla yüklemezseniz bu oluşturucuyu kullanın.

Değiştirme mesajının, küçük bir farkla özel durum mesajları yazmaya yönelik .NET Framework tasarım yönergelerine uygun olması gerekir. Yönergeler, geliştiriciler için istisna mesajlarının yazılması gerektiğini belirtiyor. Bu değiştirme mesajları cmdlet kullanıcısı için yazılmalıdır.

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

Önerilen Eylem Bilgileri

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

Çağrı bilgileri

Bir cmdlet, bir hata kaydını bildirmek için System.Management.Automation.Cmdlet.WriteError veya System.Management.Automation.Cmdlet.Throwtertainederror* 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 komut dosyasıyla ilgili bilgileri içeren bir System.Management.Automation.Invationinfo nesnesi tarafından sağlanır. Bu özellik salt okunurdur.

Ayrıca Bakınız

System.Management.Automation.Cmdlet.WriteError

System.Management.Automation.Cmdlet.Throwsonlandırma hatası*

System.Management.Automation.ErrorCategory

System.Management.Automation.Errorcategoryinfo

System.Management.Automation.ErrorRecord

System.Management.Automation.ErrorDetails

System.Management.Automation.Invokasyon bilgisi

Windows PowerShell Hata Raporlaması

Windows PowerShell Cmdlet'i Yazma

İlgili makaleler