Cmdlet’inize Sonlandırıcı Olmayan Hata Raporlama Ekleme

Cmdlet'ler, System.Management.Automation.Cmdlet.WriteError yöntemini çağırarak sonlandırıcı olmayan hataları bildirebilir ve yine de geçerli giriş nesnesi üzerinde veya diğer gelen işlem hattı nesnelerinde çalışmaya devam edebilir. Bu bölümde, giriş işleme yöntemlerinden sonlandırılmayan hataları bildiren bir cmdlet'in nasıl oluşturulacağı açıklanmaktadır.

Sonlandırılmayan hatalar (ve sonlandırma hataları) için cmdlet'in hatayı tanımlayan bir System.Management.Automation.ErrorRecord nesnesi geçirmesi gerekir. Her hata kaydı, "hata tanımlayıcısı" adlı benzersiz bir dizeyle tanımlanır. Tanımlayıcıya ek olarak, her hatanın kategorisi System.Management.Automation.ErrorCategory numaralandırması tarafından tanımlanan sabitler tarafından belirtilir. Kullanıcı, $ErrorView değişkenini "CategoryView" olarak ayarlayarak hataları kategorilerine göre görüntüleyebilir.

Hata kayıtları hakkında daha fazla bilgi için bkz. Windows PowerShell Hata Kayıtları.

Cmdlet'i tanımlama

Cmdlet oluşturmanın ilk adımı her zaman cmdlet'ini adlandırmak ve cmdlet'i uygulayan .NET sınıfını bildirmektir. Bu cmdlet işlem bilgilerini alır, dolayısıyla burada seçilen fiil adı "Get" olur. (Bilgi alma yeteneğine sahip hemen her tür cmdlet komut satırı girişini işleyebilir.) Onaylanan cmdlet fiilleri hakkında daha fazla bilgi için bkz. Cmdlet Fiil Adları.

Bu Get-Proc cmdlet'inin tanımı aşağıdadır. Bu tanımın ayrıntıları İlk Cmdlet'inizi Oluşturmaiçinde verilmiştir.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Parametreleri Tanımlama

Gerekirse, cmdlet'inizin girişi işlemek için parametreler tanımlaması gerekir. Bu Get-Proc cmdlet,Command-Line Girişİşleyen Parametreler Ekleme bölümünde açıklandığı gibi bir Name parametresi tanımlar.

Bu Get-Proc cmdlet'in Name parametresinin parametre bildirimi aşağıdadır.

[Parameter(
           Position = 0,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true
)]
[ValidateNotNullOrEmpty]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

<Parameter(Position:=0, ValueFromPipeline:=True, _
ValueFromPipelineByPropertyName:=True), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

Giriş İşleme Yöntemlerini Geçersiz Kılma

Tüm cmdlet'ler, System.Management.Automation.Cmdlet sınıfı tarafından sağlanan giriş işleme yöntemlerinden en az birini geçersiz kılmalıdır. Bu yöntemler İlk Cmdlet'inizi Oluşturmabölümünde ele alınıyor.

Uyarı

Cmdlet'iniz her kaydı mümkün olduğunca bağımsız olarak işlemelidir.

Bu Get-Proc cmdlet'i, kullanıcı veya betik tarafından sağlanan giriş için Name parametresini işlemek üzere System.Management.Automation.Cmdlet.ProcessRecord yöntemini geçersiz kılar. Bu yöntem, istenen her işlem adı veya ad sağlanmazsa tüm işlemler için işlemleri alır. Bu geçersiz kılmanın ayrıntıları İlk Cmdlet'inizi Oluşturmaiçinde verilmiştir.

Hataları Bildirirken Anımsamanız Gerekenler

System.Management.Automation.ErrorRecord bir hata yazarken cmdlet'in geçtiği nesne, çekirdeğinde bir özel durum gerektirir. Kullanılacak özel durumu belirlerken .NET yönergelerini izleyin. Temel olarak, hata mevcut bir özel durumla aynıysa, cmdlet'in bu özel durumu kullanması veya bu özel durumdan türetilmesi gerekir. Aksi takdirde, doğrudan System.Exception sınıfından yeni bir özel durum veya özel durum hiyerarşisi türetmelidir.

Hata tanımlayıcıları oluştururken (ErrorRecord sınıfının FullyQualifiedErrorId özelliği aracılığıyla erişilir) aşağıdakileri göz önünde bulundurun.

Tam tanımlayıcıyı incelerken hatanın ne olduğunu ve hatanın nereden geldiğini belirleyebilmeniz için tanılama amacıyla hedeflenen dizeleri kullanın.
İyi biçimlendirilmiş tam hata tanımlayıcısı aşağıdaki gibi olabilir.

CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

Önceki örnekte hata tanımlayıcısının (ilk belirteç) hatanın ne olduğunu ve kalan bölümün hatanın nereden geldiğini gösterdiğine dikkat edin.

Daha karmaşık senaryolar için hata tanımlayıcısı, inceleme sırasında ayrıştırılabilir noktalı bir belirteç olabilir. Bu, hata tanımlayıcısının bölümlerinin yanı sıra hata tanımlayıcısı ve hata kategorisi üzerinde de dallanmanıza olanak tanır.

Cmdlet farklı kod yollarına belirli hata tanımlayıcıları atamalıdır. Hata tanımlayıcılarının atanması için aşağıdaki bilgileri göz önünde bulundurun:

Bir hata tanımlayıcısı cmdlet yaşam döngüsü boyunca sabit kalmalıdır. Cmdlet sürümleri arasında hata tanımlayıcısının semantiğini değiştirmeyin.
Bildirilen hataya ters olarak karşılık gelen bir hata tanımlayıcısı için metin kullanın. Boşluk veya noktalama işaretleri kullanmayın.
Cmdlet'inizin yalnızca yeniden üretilebilir hata tanımlayıcıları oluşturmalarını sağlayın. Örneğin, işlem tanımlayıcısı içeren bir tanımlayıcı oluşturmamalıdır. Hata tanımlayıcıları bir kullanıcı için yalnızca aynı sorunla karşılaşan diğer kullanıcılar tarafından görülen tanımlayıcılara karşılık geldiğinde yararlıdır.

İşlenmeyen özel durumlar aşağıdaki koşullarda PowerShell tarafından yakalanmaz:

Bir cmdlet yeni bir iş parçacığı oluşturursa ve bu iş parçacığında çalışan kod işlenmeyen bir özel durum oluşturursa, PowerShell hatayı yakalamaz ve işlemi sonlandırır.
Bir nesnenin yok edicisinde veya Dispose yöntemlerinde işlenmeyen bir özel duruma neden olan kod varsa, PowerShell hatayı yakalamaz ve işlemi sonlandırır.

Sonlandırılmayan Hataları Bildirme

Giriş işleme yöntemlerinden herhangi biri, System.Management.Automation.Cmdlet.WriteError yöntemini kullanarak çıkış akışına sonlandırmayan bir hata bildirebilir.

Burada, System.Management.Automation.Cmdlet.ProcessRecord yönteminin geçersiz kılınan System.Management.Automation.Cmdlet.WriteError çağrısını gösteren bu Get-Proc cmdlet'in bir kod örneği verilmiştir. Bu durumda, cmdlet belirtilen işlem tanımlayıcısı için bir işlem bulamazsa çağrı yapılır.

protected override void ProcessRecord()
{
  // If no name parameter passed to cmdlet, get all processes.
  if (processNames == null)
  {
    WriteObject(Process.GetProcesses(), true);
  }
    else
    {
      // If a name parameter is passed to cmdlet, get and write
      // the associated processes.
      // Write a non-terminating error for failure to retrieve
      // a process.
      foreach (string name in processNames)
      {
        Process[] processes;

        try
        {
          processes = Process.GetProcessesByName(name);
        }
        catch (InvalidOperationException ex)
        {
          WriteError(new ErrorRecord(
                     ex,
                     "NameNotFound",
                     ErrorCategory.InvalidOperation,
                     name));
          continue;
        }

        WriteObject(processes, true);
      } // foreach (...
    } // else
  }

Sonlandırıcı Olmayan Hatalar Yazma Hakkında Anımsanması Gerekenler

Sonlandırılamayan bir hata için, cmdlet'in her belirli giriş nesnesi için belirli bir hata tanımlayıcısı oluşturması gerekir.

Cmdlet'in sık sık sonlandırılmayan bir hata tarafından oluşturulan PowerShell eylemini değiştirmesi gerekir. ErrorAction ve ErrorVariable parametrelerini tanımlayarak bunu yapabilir. ErrorAction parametresini tanımlıyorsanız, cmdlet System.Management.Automation.ActionPreference kullanıcı seçeneklerini sunar. Ayrıca, $ErrorActionPreference değişkenini ayarlayarak eylemi doğrudan da etkileyebilirsiniz.

Cmdlet, ErrorActionayarından etkilenmeyen ErrorVariable parametresini kullanarak sonlandırıcı olmayan hataları bir değişkene kaydedebilir. Hatalar, değişken adının önüne artı işareti (+) eklenerek mevcut bir hata değişkenine eklenebilir.

Kod Örneği

C# örnek kodunun tamamı için bkz. getProcessSample04 Örnek .

Nesne Türlerini ve Biçimlendirmeyi Tanımlama

PowerShell, .NET nesnelerini kullanarak cmdlet'ler arasında bilgi geçirir. Sonuç olarak, bir cmdlet'in kendi türünü tanımlaması veya cmdlet'in başka bir cmdlet tarafından sağlanan mevcut bir türü genişletmesi gerekebilir. Yeni türleri tanımlama veya var olan türleri genişletme hakkında daha fazla bilgi için bkz. Nesne Türlerini Genişletme ve Biçimlendirme.

Cmdlet'i oluşturma

Cmdlet'i uyguladıktan sonra, bir Windows PowerShell ek bileşeni aracılığıyla Windows PowerShell'e kaydetmeniz gerekir. Cmdlet'leri kaydetme hakkında daha fazla bilgi için bkz. Cmdlet'leri, Sağlayıcıları ve Konak Uygulamalarını Kaydetme.

Cmdlet'i test etme

Cmdlet'iniz PowerShell'e kaydedildiğinde, komut satırında çalıştırarak bunu test edebilirsiniz. Hata bildirip bildirmediğini görmek için örnek Get-Proc cmdlet'ini test edelim:

PowerShell'i başlatın ve "TEST" adlı işlemleri almak için Get-Proc cmdlet'ini kullanın.

Get-Proc -Name test

Aşağıdaki çıkış görüntülenir.

Get-Proc : Operation is not valid due to the current state of the object.
At line:1 char:9
+ Get-Proc  <<<< -Name test

Ayrıca Bkz.

İşlem Hattı Girişini İşleyen Parametreler Ekleme
Giriş İşleyen Parametreler Command-Line Ekleme
İlk Cmdlet'inizi Oluşturma
Nesne Türlerini ve Biçimlendirme Genişletmeyi
Cmdlet'leri, Sağlayıcıları ve Konak Uygulamalarını Kaydetme
Windows PowerShell Başvurusu
Cmdlet Örnekleri

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-03-25