Ausführen eines Dienststartskripts als lokales Benutzerkonto oder SystemkontoRun a service startup script as a local user or system account

Bevor eine ausführbare Service Fabric-Dienstdatei startet, können Konfigurations- oder Setupeinstellungen erforderlich sein.Before a Service Fabric service executable starts up it may be necessary to run some configuration or setup work. Beispiel: Konfiguration von Umgebungsvariablen.For example, configuring environment variables. Sie können angeben, dass ein Skript ausgeführt wird, bevor die ausführbare Dienstdatei im Dienstmanifest für den Dienst startet.You can specify a script to run before the service executable starts up in the service manifest for the service. Durch Konfigurieren einer RunAs-Richtlinie für den Setupeinstiegspunkt des Diensts können Sie das Konto ändern, unter dem die Setupdatei ausgeführt wird.By configuring a RunAs policy for the service setup entry point you can change which account the setup executable runs under. Mit einem separaten Setupeinstiegspunkt können Sie für einen kurzen Zeitraum eine Konfiguration mit hohen Berechtigungen ausführen, damit die ausführbare Diensthostdatei nicht für längere Zeiträume mit hohen Berechtigungen ausgeführt werden muss.A separate setup entry point allows you to run high-privileged configuration for a short period of time so the service host executable doesn't need to run with high privileges for extended periods of time.

Der Setupeinstiegspunkt (SetupEntryPoint im Dienstmanifest) ist ein privilegierter Einstiegspunkt, der standardmäßig mit den gleichen Anmeldeinformationen wie Service Fabric (meist mit dem Konto NetworkService) vor jedem anderen Einstiegspunkt ausgeführt wird.The setup entry point (SetupEntryPoint in the service manifest) is a privileged entry point that by default runs with the same credentials as Service Fabric (typically the NetworkService account) before any other entry point. Die durch EntryPoint angegebene ausführbare Datei ist üblicherweise der Diensthost mit langer Ausführungsdauer.The executable that is specified by EntryPoint is typically the long-running service host. Die von EntryPoint angegebene ausführbare Datei wird ausgeführt, nachdem SetupEntryPoint erfolgreich beendet wurde.The EntryPoint executable is run after the SetupEntryPoint executable exits successfully. Der resultierende Prozess wird überwacht und neu gestartet (er beginnt wieder mit SetupEntryPoint), sofern er beendet wird oder abstürzt.The resulting process is monitored and restarted, and begins again with SetupEntryPoint if it ever terminates or crashes.

Konfigurieren des Setupeinstiegspunkts für DiensteConfigure the service setup entry point

Im Folgenden finden Sie ein einfaches Dienstmanifestbeispiel für einen zustandslosen Dienst, in dem ein Setupskript MySetup.bat im Dienst-SetupEntryPoint angegeben wird.The following is a simple service manifest example for a stateless service that specifies a setup script MySetup.bat in the service SetupEntryPoint. Mit Arguments werden dem Skript während der Ausführung Argumente übergeben.Arguments is used to pass arguments to the script when it runs.

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="MyStatelessServicePkg"
                 Version="1.0.0"
                 xmlns="http://schemas.microsoft.com/2011/01/fabric"
                 xmlns:xsd="https://www.w3.org/2001/XMLSchema"
                 xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
  <Description>An example service manifest.</Description>
  <ServiceTypes>
    <StatelessServiceType ServiceTypeName="MyStatelessServiceType" />
  </ServiceTypes>

  <!-- Code package is your service executable. -->
  <CodePackage Name="Code" Version="1.0.0">
    <SetupEntryPoint>
      <ExeHost>
        <Program>MySetup.bat</Program>
        <Arguments>MyValue</Arguments>
        <WorkingFolder>Work</WorkingFolder>        
      </ExeHost>
    </SetupEntryPoint>
    <EntryPoint>
      <ExeHost>
        <Program>MyStatelessService.exe</Program>
      </ExeHost>
    </EntryPoint>
  </CodePackage>

  <ConfigPackage Name="Config" Version="1.0.0" />

  <Resources>
    <Endpoints>
      <Endpoint Name="ServiceEndpoint" />
    </Endpoints>
  </Resources>
</ServiceManifest>

Konfigurieren der Richtlinie für einen Setupeinstiegspunkt für DiensteConfigure the policy for a service setup entry point

Standardmäßig wird die ausführbare Setupeinstiegspunkt-Datei des Diensts unter den gleichen Anmeldeinformationen wie Service Fabric ausgeführt (in der Regel das NetworkService-Konto).By default, the service setup entry point executable runs under the same credentials as Service Fabric (typically the NetworkService account). Im Anwendungsmanifest können Sie die Sicherheitsberechtigungen zur Ausführung des Startskripts unter einem lokalen Systemkonto oder einem Administratorkonto ändern.In the application manifest, you can change the security permissions to run the startup script under a local system account or an administrator account.

Konfigurieren der Richtlinie mithilfe eines lokalen SystemkontosConfigure the policy by using a local system account

Das folgende Anwendungsmanifestbeispiel zeigt das Konfigurieren des Dienst-Setupeinstiegspunkts für die Ausführung unter dem Administratorkonto des Benutzers (SetupAdminUser).The following application manifest example shows how to configure the service setup entry point to run under user administrator account (SetupAdminUser).

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" ApplicationTypeName="MyApplicationType" ApplicationTypeVersion="1.0.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Parameters>
    <Parameter Name="MyStatelessService_InstanceCount" DefaultValue="-1" />
  </Parameters>
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="MyStatelessServicePkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <Policies>
      <RunAsPolicy CodePackageRef="Code" UserRef="SetupAdminUser" EntryPointType="Setup" />
    </Policies>
  </ServiceManifestImport>
  <DefaultServices>
    <Service Name="MyStatelessService" ServicePackageActivationMode="ExclusiveProcess">
      <StatelessService ServiceTypeName="MyStatelessServiceType" InstanceCount="[MyStatelessService_InstanceCount]">
        <SingletonPartition />
      </StatelessService>
    </Service>
  </DefaultServices>
  <Principals>
    <Users>
      <User Name="SetupAdminUser">
        <MemberOf>
          <SystemGroup Name="Administrators" />
        </MemberOf>
      </User>
    </Users>
  </Principals>
</ApplicationManifest>

Erstellen Sie zuerst den Abschnitt Principals mit einem Benutzernamen, z.B. „SetupAdminUser“.First, create a Principals section with a user name, such as SetupAdminUser. Das SetupAdminUser-Benutzerkonto ist ein Mitglied der Systemgruppe „Administratoren“.The SetupAdminUser user account is a member of the Administrators system group.

Konfigurieren Sie als Nächstes im Abschnitt ServiceManifestImport eine Richtlinie, gemäß der dieser Prinzipal auf SetupEntryPoint angewendet werden kann.Next, under the ServiceManifestImport section, configure a policy to apply this principal to SetupEntryPoint. Diese Richtlinie teilt Service Fabric mit, dass die Datei MySetup.bat als SetupAdminUser (mit Administratorrechten) ausgeführt werden soll.This policy tells Service Fabric that when the MySetup.bat file is run it should run as SetupAdminUser ( with administrator privileges). Da Sie keine Richtlinie auf den primären Einstiegspunkt angewendet haben, wird der Code in MyServiceHost.exe unter dem Systemkonto NetworkService ausgeführt.Since you have not applied a policy to the main entry point, the code in MyServiceHost.exe runs under the system NetworkService account. Dies ist das Standardkonto, unter dem alle Diensteinstiegspunkte ausgeführt werden.This is the default account that all service entry points are run as.

Konfigurieren der Richtlinie mithilfe eines lokalen SystemkontosConfigure the policy by using local system accounts

Häufig ist es von Vorteil, das Startskript mithilfe eines lokalen Systemkontos statt eines Administratorkontos auszuführen.Often, it's preferable to run the startup script using a local system account rather than an administrator account. Die Ausführung der RunAs-Richtlinie als Mitglied der Administratorgruppe funktioniert in der Regel nicht gut, da die Benutzerkontensteuerung (User Access Control, UAC) auf Computern standardmäßig aktiviert ist.Running the RunAs policy as a member of the Administrators group typically doesn’t work well because computers have User Access Control (UAC) enabled by default. In solchen Fällen wird empfohlen, den SetupEntryPoint als LocalSystem auszuführen, anstatt als lokaler Benutzer, der der Administratorgruppe hinzugefügt wurde.In such cases, the recommendation is to run the SetupEntryPoint as LocalSystem, instead of as a local user added to Administrators group. Das folgende Beispiel zeigt, wie SetupEntryPoint zur Ausführung als LocalSystem festgelegt wird:The following example shows setting the SetupEntryPoint to run as LocalSystem:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" ApplicationTypeName="MyApplicationType" ApplicationTypeVersion="1.0.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Parameters>
    <Parameter Name="MyStatelessService_InstanceCount" DefaultValue="-1" />
  </Parameters>
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="MyStatelessServicePkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <Policies>
         <RunAsPolicy CodePackageRef="Code" UserRef="SetupLocalSystem" EntryPointType="Setup" />
      </Policies>
  </ServiceManifestImport>
  <DefaultServices>
    <Service Name="MyStatelessService" ServicePackageActivationMode="ExclusiveProcess">
      <StatelessService ServiceTypeName="MyStatelessServiceType" InstanceCount="[MyStatelessService_InstanceCount]">
        <SingletonPartition />
      </StatelessService>
    </Service>
  </DefaultServices>
  <Principals>
      <Users>
         <User Name="SetupLocalSystem" AccountType="LocalSystem" />
      </Users>
   </Principals>
</ApplicationManifest>

Hinweis

Für Linux-Cluster können Sie den AccountType als LocalSystem bestimmen, um einen Dienst oder einen Setupeinstiegspunkt als Stamm auszuführen.For Linux clusters, to run a service or the setup entry point as root, you can specify the AccountType as LocalSystem.

Ausführen eines Skripts vom SetupeinstiegspunktRun a script from the setup entry point

Fügen Sie dem Projekt jetzt ein Startskript hinzu, das mit Administratorberechtigungen ausgeführt wird.Now add a start up script to the project to run under administrator privileges.

Klicken Sie in Visual Studio mit der rechten Maustaste auf das Dienstprojekt, und fügen Sie eine neue Datei mit dem Namen MySetup.bat hinzu.In Visual Studio, right-click the service project and add a new file called MySetup.bat.

Stellen Sie anschließend sicher, dass die Datei MySetup.bat im Dienstpaket enthalten ist.Next, ensure that the MySetup.bat file is included in the service package. Standardmäßig ist dies nicht der Fall.By default, it is not. Wählen Sie die Datei aus, klicken Sie mit der rechten Maustaste, um das Kontextmenü zu öffnen, und wählen Sie Eigenschaften.Select the file, right-click to get the context menu, and choose Properties. Stellen Sie im Dialogfeld „Eigenschaften“ sicher, dass In Ausgabeverzeichnis kopieren auf Kopieren, wenn neuer festgelegt ist.In the Properties dialog box, ensure that Copy to Output Directory is set to Copy if newer. Der folgende Screenshot zeigt dies.See the following screenshot.

Visual Studio – Batchdatei für „CopyToOutput“ für „SetupEntryPoint“

Bearbeiten Sie jetzt die Datei MySetup.bat, fügen Sie der folgenden Befehlsgruppe eine Systemumgebungsvariable hinzu, und geben Sie eine Textdatei aus:Now edit the MySetup.bat file and add the following commands set a system environment variable and output a text file:

REM Set a system environment variable. This requires administrator privilege
setx -m TestVariable %*
echo System TestVariable set to > out.txt
echo %TestVariable% >> out.txt

REM To delete this system variable us
REM REG delete "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v TestVariable /f

Als Nächstes müssen Sie die Projektmappe erstellen und in einem lokalen Entwicklungscluster bereitstellen.Next, build and deploy the solution to a local development cluster. Nachdem der Dienst wie im Service Fabric Explorer angezeigt gestartet wurde, können Sie erkennen, dass die Datei „MySetup.bat“ auf zwei Arten erfolgreich war.After the service has started, as shown in Service Fabric Explorer, you can see that the MySetup.bat file was successful in a two ways. Öffnen Sie eine PowerShell-Eingabeaufforderung, und geben Sie Folgendes ein:Open a PowerShell command prompt and type:

PS C:\ [Environment]::GetEnvironmentVariable("TestVariable","Machine")
MyValue

Notieren Sie anschließend den Namen des Knotens, auf dem der Dienst bereitgestellt und im Service Fabric Explorer gestartet wurde.Then, note the name of the node where the service was deployed and started in Service Fabric Explorer. Beispiel: Knoten 2.For example, Node 2. Navigieren Sie als Nächstes zum Arbeitsordner der Anwendungsinstanz, um die Datei „out.txt“ zu ermitteln, in der der Wert von TestVariable angezeigt wird.Next, navigate to the application instance work folder to find the out.txt file that shows the value of TestVariable. Wenn dieser Dienst z.B. auf Knoten 2 bereitgestellt wurde, können Sie für MyApplicationType auf diesen Pfad zugreifen:For example, if this service was deployed to Node 2, then you can go to this path for the MyApplicationType:

C:\SfDevCluster\Data\_App\Node.2\MyApplicationType_App\work\out.txt

Ausführen von PowerShell-Befehlen über einen SetupeinstiegspunktRun PowerShell commands from a setup entry point

Zum Ausführen von PowerShell über den Punkt SetupEntryPoint können Sie PowerShell.exe in einer Batchdatei ausführen, die auf eine PowerShell-Datei verweist.To run PowerShell from the SetupEntryPoint point, you can run PowerShell.exe in a batch file that points to a PowerShell file. Fügen Sie zuerst dem Dienstprojekt eine PowerShell-Datei hinzu, z.B. MySetup.ps1.First, add a PowerShell file to the service project--for example, MySetup.ps1. Denken Sie daran, die Eigenschaft Kopieren, wenn neuer so festzulegen, dass die Datei in das Dienstpaket einbezogen wird.Remember to set the Copy if newer property so that the file is also included in the service package. Das folgende Beispiel zeigt eine Beispielbatchdatei zum Starten einer PowerShell-Datei namens „MySetup.ps1“, mit der die Systemumgebungsvariable TestVariable festgelegt wird.The following example shows a sample batch file that starts a PowerShell file called MySetup.ps1, which sets a system environment variable called TestVariable.

„MySetup.bat“ zum Starten der PowerShell-Datei:MySetup.bat to start a PowerShell file:

powershell.exe -ExecutionPolicy Bypass -Command ".\MySetup.ps1"

Fügen Sie in der PowerShell-Datei Folgendes ein, um eine Systemumgebungsvariable festzulegen:In the PowerShell file, add the following to set a system environment variable:

[Environment]::SetEnvironmentVariable("TestVariable", "MyValue", "Machine")
[Environment]::GetEnvironmentVariable("TestVariable","Machine") > out.txt

Hinweis

Standardmäßig sucht die Batchdatei bei der Ausführung in dem Anwendungsordner work nach Dateien.By default, when the batch file runs, it looks at the application folder called work for files. In diesem Fall soll „MySetup.bat“ bei der Ausführung die Datei „MySetup.ps1“ im gleichen Ordner suchen, also im Anwendungsordner CodePackage.In this case, when MySetup.bat runs, we want this to find the MySetup.ps1 file in the same folder, which is the application code package folder. Um diesen Ordner zu ändern, legen Sie den Arbeitsordner fest:To change this folder, set the working folder:

<SetupEntryPoint>
    <ExeHost>
    <Program>MySetup.bat</Program>
    <WorkingFolder>CodePackage</WorkingFolder>
    </ExeHost>
</SetupEntryPoint>

Lokales Debuggen eines Startskripts mit KonsolenumleitungDebug a startup script locally using console redirection

Gelegentlich ist es hilfreich, zum Debuggen die Konsolenausgabe der Ausführung eines Setupskripts auszuwerten.Occasionally, it's useful for debugging purposes to see the console output from running a setup script. Sie können eine Richtlinie für die Konsolenumleitung am Setupeinstiegspunkt im Dienstmanifest festlegen, die die Ausgabe in eine Datei schreibt.You can set a console redirection policy on the setup entry point in the service manifest, which writes the output to a file. Die Dateiausgabe wird in den Anwendungsordner log auf dem Clusterknoten geschrieben, auf dem die Anwendung bereitgestellt und ausgeführt wird.The file output is written to the application folder called log on the cluster node where the application is deployed and run.

Warnung

Verwenden Sie die Richtlinie zur Konsolenumleitung nie in einer Anwendung, die in der Produktionsumgebung bereitgestellt wurde, da sich dies auf das Anwendungsfailover auswirken kann.Never use the console redirection policy in an application that is deployed in production because this can affect the application failover. Verwenden Sie diese nur für die lokale Entwicklung und das Debuggen.Only use this for local development and debugging purposes.

Das folgende Dienstmanifestbeispiel zeigt das Festlegen der Konsolenumleitung mit einem FileRetentionCount-Wert:The following service manifest example shows setting the console redirection with a FileRetentionCount value:

<SetupEntryPoint>
    <ExeHost>
    <Program>MySetup.bat</Program>
    <WorkingFolder>CodePackage</WorkingFolder>
    <ConsoleRedirection FileRetentionCount="10"/>
    </ExeHost>
</SetupEntryPoint>

Wenn Sie nun die Datei „MySetup.ps1“ so ändern, dass ein Echo-Befehl geschrieben wird, wird zu Debugzwecken in die Ausgabedatei geschrieben:If you now change the MySetup.ps1 file to write an Echo command, this will write to the output file for debugging purposes:

Echo "Test console redirection which writes to the application log folder on the node that the application is deployed to"

Warnung

Nachdem Sie Ihr Skript gedebuggt haben, entfernen Sie diese Richtlinie zur Konsolenumleitung sofort.After you debug your script, immediately remove this console redirection policy.

Nächste SchritteNext steps