Felhasználói üzenetek hozzáadása a parancsmaghoz

A parancsmagok többféle üzenetet is írhatnak, amelyeket a Windows PowerShell-futtatókörnyezet jeleníthet meg a felhasználó számára. Ezek az üzenetek a következő típusokat tartalmazzák:

• Részletes üzenetek, amelyek általános felhasználói adatokat tartalmaznak.

• Hibaelhárítási információkat tartalmazó üzenetek hibakeresése.

• Figyelmeztető üzenetek, amelyek értesítést tartalmaznak arról, hogy a parancsmag olyan műveletet hajt végre, amely váratlan eredményeket okozhat.

• A folyamatjelentés üzenetei, amelyek információt tartalmaznak arról, hogy a parancsmag mennyi munkát végzett el egy hosszú ideig tartó művelet végrehajtásakor.

A parancsmag által írható üzenetek száma és a parancsmag által írt üzenetek típusa nincs korlátozva. Minden üzenet írása egy adott hívással történik a parancsmag bemeneti feldolgozási módszerén belül.

A parancsmag definiálása

A parancsmag létrehozásának első lépése mindig a parancsmag elnevezése és a parancsmagot implementáló .NET-osztály deklarálása. Bármilyen parancsmag írhat felhasználói értesítéseket a bemeneti feldolgozási módszereiből; Így ezt a parancsmagot általában bármilyen olyan igével elnevezheti, amely jelzi, hogy a parancsmag milyen rendszermódosításokat hajt végre. A jóváhagyott parancsmag-parancsmagokkal kapcsolatos további információkért lásd parancsmagok parancsmagjának nevei.

A Stop-Proc parancsmag a rendszer módosítására lett tervezve; ezért a .NET-osztály System.Management.Automation.CmdletAttribute deklarációjának tartalmaznia kell a SupportsShouldProcess attribútum kulcsszót, és truekell beállítania.

A következő kód a Stop-Proc parancsmagosztály definíciója. A definícióval kapcsolatos további információkért lásd: A rendszermódosító parancsmag létrehozása.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

A rendszermódosítás paramétereinek meghatározása

A Stop-Proc parancsmag három paramétert határoz meg: Name, Forceés PassThru. A paraméterek definiálásáról további információt a A rendszermódosító parancsmag létrehozása című témakörben talál.

Itt található a Stop-Proc parancsmag paraméterdeklarációja.

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

/// <summary>
/// Specify the Force parameter that allows the user to override
/// the ShouldContinue call to force the stop operation. This
/// parameter should always be used with caution.
/// </summary>
[Parameter]
public SwitchParameter Force
{
  get { return force; }
  set { force = value; }
}
private bool force;

/// <summary>
/// Specify the PassThru parameter that allows the user to specify
/// that the cmdlet should pass the process object down the pipeline
/// after the process has been stopped.
/// </summary>
[Parameter]
public SwitchParameter PassThru
{
  get { return passThru; }
  set { passThru = value; }
}
private bool passThru;

Bemeneti feldolgozási módszer felülírása

A parancsmagnak felül kell bírálnia egy bemeneti feldolgozási módszert, leggyakrabban System.Management.Automation.Cmdlet.ProcessRecord. Ez a Stop-Proc parancsmag felülbírálja a System.Management.Automation.Cmdlet.ProcessRecord bemeneti feldolgozási módszert. A Stop-Proc parancsmag ezen implementációjában a rendszer részletes üzenetek, hibakeresési és figyelmeztető üzenetek írására kéri a hívásokat.

Megjegyzés

A system.Management.Automation.Cmdlet.ShouldProcess és System.Management.Automation.Cmdlet.ShouldContinue metódusok meghívásáról további információt a Rendszermódosító parancsmag létrehozása című témakörben talál.

Részletes üzenet írása

A System.Management.Automation.Cmdlet.WriteVerbose metódus olyan általános felhasználói szintű információk írására szolgál, amelyek nem kapcsolódnak adott hibafeltételekhez. A rendszergazda ezután felhasználhatja ezeket az információkat más parancsok feldolgozásához. Ezenkívül az ezzel a módszerrel írt információkat szükség szerint honosítjuk.

A Stop-Proc parancsmag alábbi kódja két hívást jelenít meg a System.Management.Automation.Cmdlet.WriteVerbose metódushoz a System.Management.Automation.Cmdlet.ProcessRecord metódus felülbírálásából.

message = String.Format("Attempting to stop process \"{0}\".", name);
WriteVerbose(message);

message = String.Format("Stopped process \"{0}\", pid {1}.",
                        processName, process.Id);

WriteVerbose(message);

Hibakeresési üzenet írása

A System.Management.Automation.Cmdlet.WriteDebug metódussal olyan hibakeresési üzeneteket írhat, amelyek a parancsmag működésének hibaelhárítására használhatók. A hívás egy bemeneti feldolgozási módszerből történik.

Megjegyzés

A Windows PowerShell egy Debug paramétert is definiál, amely részletes és hibakeresési információkat is tartalmaz. Ha a parancsmag támogatja ezt a paramétert, nem kell meghívnia System.Management.Automation.Cmdlet.WriteDebug ugyanabban a kódban, amely meghívja System.Management.Automation.Cmdlet.WriteVerbose.

A minta Stop-Proc parancsmag következő két kódszakasza a System.Management.Automation.Cmdlet.Cmdlet.WriteDebug metódusra irányuló hívásokat jeleníti meg a System.Management.Automation.Cmdlet.ProcessRecord metódus felülbírálásából.

Ez a hibakeresési üzenet közvetlenül a System.Management.Automation.Cmdlet.ShouldProcess meghívása előtt lesz megírva.

message =
          String.Format("Acquired name for pid {0} : \"{1}\"",
                       process.Id, processName);
WriteDebug(message);

Ez a hibakeresési üzenet közvetlenül a System.Management.Automation.Cmdlet.WriteObject meghívása előtt lesz megírva.

message =
         String.Format("Writing process \"{0}\" to pipeline",
         processName);
WriteDebug(message);
WriteObject(process);

A Windows PowerShell automatikusan átirányítja a System.Management.Automation.Cmdlet.WriteDebug hívásokat a nyomkövetési infrastruktúrához és a parancsmagokhoz. Ez lehetővé teszi, hogy a metódushívások a parancsmagon belül további fejlesztési műveletek nélkül legyenek nyomon követve az üzemeltetési alkalmazásra, fájlra vagy hibakeresőre. Az alábbi parancssori bejegyzés egy nyomkövetési műveletet valósít meg.

PS> Trace-Expression Stop-Proc -File proc.log -Command Stop-Proc jegyzettömb

Figyelmeztető üzenet írása

A rendszer a System.Management.Automation.Cmdlet.Cmdlet.WriteWarning metódussal figyelmeztetést ír, ha a parancsmag egy váratlan eredményt adó művelet végrehajtására készül, például egy írásvédett fájl felülírására.

A minta Stop-Proc parancsmag alábbi kódja a System.Management.Automation.Cmdlet.Cmdlet.WriteWarning metódus meghívását mutatja be a System.Management.Automation.Cmdlet.ProcessRecord metódus felülbírálásából.

 if (criticalProcess)
 {
   message =
             String.Format("Stopping the critical process \"{0}\".",
                           processName);
   WriteWarning(message);
} // if (criticalProcess...

Folyamatjelző üzenet írása

A System.Management.Automation.Cmdlet.WriteProgress a folyamatjelző üzenetek írására szolgál, ha a parancsmagműveletek végrehajtása hosszabb időt vesz igénybe. A System.Management.Automation.Cmdlet.WriteProgress hívása egy System.Management.Automation.Progressrecord objektumot ad át, amelyet a rendszer az üzemeltetési alkalmazásnak küld renderelés céljából a felhasználónak.

Megjegyzés

Ez a Stop-Proc parancsmag nem tartalmaz hívást a System.Management.Automation.Cmdlet.WriteProgress metódushoz.

Az alábbi kód egy példa egy olyan folyamatjelző üzenetre, amelyet egy olyan parancsmag írt, amely egy elemet próbál másolni.

int myId = 0;
string myActivity = "Copy-item: Copying *.* to C:\abc";
string myStatus = "Copying file bar.txt";
ProgressRecord pr = new ProgressRecord(myId, myActivity, myStatus);
WriteProgress(pr);

pr.RecordType = ProgressRecordType.Completed;
WriteProgress(pr);

Kódminta

A teljes C#-mintakódért lásd StopProcessSample02 Minta.

Objektumtípusok és formázás definiálása

A Windows PowerShell .NET-objektumokkal továbbítja az adatokat a parancsmagok között. Következésképpen előfordulhat, hogy egy parancsmagnak meg kell határoznia a saját típusát, vagy előfordulhat, hogy a parancsmagnak ki kell terjesztenie egy másik parancsmag által biztosított meglévő típust. További információ az új típusok definiálásáról vagy a meglévő típusok kibővítéséről: Objektumtípusok és formázás kiterjesztése.

A parancsmag létrehozása

A parancsmag implementálása után egy Windows PowerShell beépülő modulon keresztül regisztrálnia kell azt a Windows PowerShellben. A parancsmagok regisztrálásáról további információt a parancsmagok, szolgáltatók és gazdagépalkalmazások .

A parancsmag tesztelése

Ha a parancsmag regisztrálva lett a Windows PowerShellben, a parancssorban futtatva tesztelheti. Teszteljük a minta Stop-Proc parancsmagot. A parancssori parancsmagok használatáról további információt a Windows PowerShell – első lépések című témakörben talál.

• Az alábbi parancssori bejegyzés Stop-Proc használatával állítja le a "JEGYZETTÖMB" nevű folyamatot, részletes értesítéseket ad meg, és hibakeresési információkat nyomtat.

  PS> Stop-Proc -Name notepad -Verbose -Debug
  

  Megjelenik a következő kimenet.

  VERBOSE: Attempting to stop process " notepad ".
  DEBUG: Acquired name for pid 5584 : "notepad"
  
  Confirm
  Continue with this operation?
  [Y] Yes  [A] Yes to All  [H] Halt Command  [S] Suspend  [?] Help (default is "Y"): Y
  
  Confirm
  Are you sure you want to perform this action?
  Performing operation "Stop-Proc" on Target "notepad (5584)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
  VERBOSE: Stopped process "notepad", pid 5584.
  

Lásd még:

A rendszer módosító parancsmag létrehozása

Windows PowerShell-parancsmag létrehozása

Objektumtípusok és formázás kiterjesztése

Parancsmagok, szolgáltatók és gazdagépalkalmazások regisztrálása

Windows PowerShell SDK