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

Cikk
09/24/2021

A parancsmagok számos típusú üzenetet írhatnak, amelyek megjeleníthetőek a Windows PowerShell számára. Ezek az üzenetek a következő típusokat tartalmazzák:

Általános felhasználói adatokat tartalmazó részletes üzenetek.
Hibaelhárítási információkat tartalmazó üzenetek hibakeresése.
Figyelmeztető üzenetek, amelyek arról szóló értesítést tartalmaznak, hogy a parancsmag váratlan eredményeket tartalmazó műveletet fog végrehajtani.
Előrehaladási jelentésüzenetek, amelyek információt tartalmaznak arról, hogy mennyi munkát fejeződött be a parancsmag egy hosszú ideig tartó művelet végrehajtásakor.

A parancsmag által írható üzenetek száma vagy a parancsmag által megírt üzenetek típusa nincs korlátokban. Minden üzenet úgy íródott, hogy egy adott hívást küld a parancsmag bemeneti feldolgozási metódusán belülről.

A parancsmag meghatározása

A parancsmagok létrehozásának első lépése mindig a parancsmag elnevezése és a parancsmagot megvalósító .NET-osztály deklarációja. Bármilyen parancsmag írhat felhasználói értesítéseket a bemeneti feldolgozási metódusaiból; Így a parancsmagnak általában bármilyen olyan parancs használatával nevet kaphat, amely jelzi, hogy milyen rendszermódosításokat hajt végre a parancsmag. A jóváhagyott parancsmag-parancsmagokkal kapcsolatos további információkért lásd: Parancsmag-parancsmagok 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ója tartalmazza az attribútum kulcsszót, és a következőre SupportsShouldProcess kell beállítani: true .

A következő kód a parancsmagosztály Stop-Proc definíciója. További információ erről a definícióról: Creating a Cmdlet that Modififies the System.

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

Rendszermódosítás paramétereinek definiálása

A Stop-Proc parancsmag három paramétert határoz meg: Name , Force és PassThru . További információ a paraméterek meghatározásáról: Creating a Cmdlet that Modififies the System.

Lássunk egy paraméterdeklarációt a Stop-Proc parancsmaghoz.

[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 metódus felülbírálása

A parancsmagnak felül kell bírálni egy bemeneti feldolgozási módszert, amely leggyakrabban System.Management.Automation.Cmdlet.ProcessRecordlesz. Ez Stop-Proc parancsmag felülbírálja a System.Management.Automation.Cmdlet.ProcessRecord bemeneti feldolgozási metódust. A Stop-Proc parancsmag ezen implementációja során a rendszer részletes üzeneteket, hibakeresési üzeneteket és figyelmeztető üzeneteket ír.

Megjegyzés

További információ arról, hogy ez a metódus hogyan hívja meg a System.Management.Automation.Cmdlet.ShouldProcess és System.Management.Automation.Cmdlet.ShouldContinue metódusokat: Creating a Cmdlet that Modifies the System.

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 használható, amelyek nem kapcsolódnak adott hibafeltételekhez. A rendszergazda ezután felhasználhatja ezeket az információkat más parancsok feldolgozásának folytatásához. Emellett az ezzel a módszerrel írt minden információt szükség szerint honosítottnak kell lennie.

A Stop-Proc-parancsmag alábbi kódja két hívást mutat be a System.Management.Automation.Cmdlet.WriteVerbose metódushoz a System.Management.Automation.Cmdlet.ProcessRecord metódus felülbírálása alapján.

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ódus hibakeresési üzenetek írására használható, amelyek a parancsmag működésének hibaelhárítására használhatók. A hívás egy bemeneti feldolgozási metódusból történt.

Megjegyzés

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

A minta Stop-Proc-parancsmag következő két kódszakasza a System.Management.Automation.Cmdlet.WriteDebug metódus hívásait mutatja be a System.Management.Automation.Cmdlet.ProcessRecord metódus felülbírálásából.

Ezt a hibakeresési üzenetet a rendszer közvetlenül a System.Management.Automation.Cmdlet.ShouldProcess előtt írja.

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 előtt íródott.

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

Windows PowerShell a System.Management.Automation.Cmdlet.WriteDebug hívásokat automatikusan a nyomkövetési infrastruktúrához és parancsmagokhoz. Ez lehetővé teszi, hogy a metódushívások nyomon követhetők az üzemeltető alkalmazáshoz, egy fájlhoz vagy hibakeresőhez anélkül, hogy további fejlesztési munkát kellene eszközleni a parancsmagon belül. Az alábbi parancssori bejegyzés 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 System.Management.Automation.Cmdlet.WriteWarning metódus figyelmeztetést ír, amikor a parancsmag váratlan eredményt jelző műveletet hajt végre, például felülír egy csak olvasható fájlt.

A Stop-Proc-parancsmag mintakódja a System.Management.Automation.Cmdlet.WriteWarning metódus hí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 folyamatüzenetek írására használatos, ha a parancsmag-műveletek hosszabb ideig tart. A System.Management.Automation.Cmdlet.WriteProgress hívása átadja a System.Management.Automation.Progressrecord objektumot, amely a felhasználónak való renderelésre lesz elküldve az üzemeltető alkalmazásnak.

Megjegyzés

Ez Stop-Proc parancsmag nem tartalmazza a System.Management.Automation.Cmdlet.WriteProgress metódus hívását.

Az alábbi kód egy példa egy elem másolását megkísérlő parancsmag által írt folyamatüzenetre.

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 tekintse meg a StopProcessSample02 mintát.

Objektumtípusok és formázás meghatározása

Windows PowerShell .NET-objektumok használatával továbbítja az információkat a parancsmagok között. Emiatt előfordulhat, hogy egy parancsmagnak meg kell határoznia a saját típusát, vagy a parancsmagnak ki kell terjesztenie egy másik parancsmag által biztosított meglévő típust. További információ az új típusok meghatározásáról vagy a meglévő típusok kiterjesztéséről: Extending Object Types and Formatting (Az objektumtípusok kiterjesztése és formázása).

A parancsmag kiépítése

A parancsmagot a megvalósítása után regisztrálni kell a Windows PowerShell egy Windows PowerShell beépülő modulon keresztül. További információ a parancsmagok regisztrálásról: Parancsmagok, szolgáltatók és gazdaalkalmazások regisztrálása.

A parancsmag tesztelése

Miután regisztrálta a parancsmagot a Windows PowerShell, a parancssorban futtatva tesztelheti. Teszteljük a minta Stop-Proc parancsmagot. A parancsmagok parancssorból való használatával kapcsolatos további információkért lásd: Ismerkedés a Windows PowerShell.

A következő parancssori bejegyzés a Stop-Proc leállítja a "NOTEPAD" nevű folyamatot, részletes értesítéseket küld, és hibakeresési információkat nyomtat ki.

PS> stop-proc -Name notepad -Verbose -Debug

Az alábbi kimenet jelenik meg.

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.