PowerShell DSC-ErweiterungPowerShell DSC Extension

ÜbersichtOverview

Die PowerShell-DSC-Erweiterung für Windows wird von Microsoft veröffentlicht und unterstützt.The PowerShell DSC Extension for Windows is published and supported by Microsoft. Die Erweiterung lädt eine PowerShell-DSC-Konfiguration auf einer Azure-VM hoch und wendet diese an.The extension uploads and applies a PowerShell DSC Configuration on an Azure VM. Die DSC-Erweiterung richtet einen Aufruf an PowerShell DSC, um die empfangene DSC-Konfiguration auf der VM in Kraft zu setzen.The DSC Extension calls into PowerShell DSC to enact the received DSC configuration on the VM. Dieses Dokument enthält ausführliche Informationen zu den unterstützten Plattformen, Konfigurationen und Bereitstellungsoptionen für die DSC-VM-Erweiterung für Windows.This document details the supported platforms, configurations, and deployment options for the DSC virtual machine extension for Windows.

VoraussetzungenPrerequisites

BetriebssystemOperating system

Die DSC-Erweiterung unterstützt die folgenden Betriebssysteme:The DSC Extension supports the following OS's

Windows Server 2019, Windows Server 2016, Windows Server 2012R2, Windows Server 2012, Windows Server 2008 R2 SP1, Windows Client 7/8.1/10Windows Server 2019, Windows Server 2016, Windows Server 2012R2, Windows Server 2012, Windows Server 2008 R2 SP1, Windows Client 7/8.1/10

InternetkonnektivitätInternet connectivity

Für die DSC-Erweiterung ist es erforderlich, dass der virtuelle Zielcomputer in der Lage ist, mit Azure zu kommunizieren, und der Speicherort des Konfigurationspakets (ZIP-Datei) außerhalb von Azure liegt.The DSC extension for Windows requires that the target virtual machine is able to communicate with Azure and the location of the configuration package (.zip file) if it is stored in a location outside of Azure.

ErweiterungsschemaExtension schema

Der folgende JSON-Code zeigt das Schema für den Bereich mit den Einstellungen der DSC-Erweiterung in einer Azure Resource Manager-Vorlage.The following JSON shows the schema for the settings portion of the DSC Extension in an Azure Resource Manager template.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "Microsoft.Powershell.DSC",
  "apiVersion": "2018-10-01",
  "location": "<location>",
  "properties": {
    "publisher": "Microsoft.Powershell",
    "type": "DSC",
    "typeHandlerVersion": "2.77",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "wmfVersion": "latest",
        "configuration": {
            "url": "http://validURLToConfigLocation",
            "script": "ConfigurationScript.ps1",
            "function": "ConfigurationFunction"
        },
        "configurationArguments": {
            "argument1": "Value1",
            "argument2": "Value2"
        },
        "configurationData": {
            "url": "https://foo.psd1"
        },
        "privacy": {
            "dataCollection": "enable"
        },
        "advancedOptions": {
            "forcePullAndApply": false,
            "downloadMappings": {
             "specificDependencyKey": "https://myCustomDependencyLocation"
            }
        } 
    },
    "protectedSettings": {
        "configurationArguments": {
            "parameterOfTypePSCredential1": {
                "userName": "UsernameValue1",
                "password": "PasswordValue1"
            },
            "parameterOfTypePSCredential2": {
                "userName": "UsernameValue2",
                "password": "PasswordValue2"
            }
        },
        "configurationUrlSasToken": "?g!bber1sht0k3n",
        "configurationDataUrlSasToken": "?dataAcC355T0k3N"
    }
  }
}

EigenschaftswerteProperty values

NameName Wert/BeispielValue / Example DatentypData Type
apiVersionapiVersion 2018-10-012018-10-01 datedate
publisherpublisher Microsoft.Powershell.DSCMicrosoft.Powershell.DSC stringstring
typetype DSCDSC stringstring
typeHandlerVersiontypeHandlerVersion 2.772.77 INTint

Eigenschaftswerte der EinstellungenSettings Property values

NameName DatentypData Type BESCHREIBUNGDescription
settings.wmfVersionsettings.wmfVersion stringstring Gibt die Version von Windows Management Framework an, die auf Ihrem virtuellen Computer installiert sein muss.Specifies the version of the Windows Management Framework that should be installed on your VM. Wenn diese Eigenschaft auf „latest“ festgelegt ist, wird die aktuelle Version von WMF installiert.Setting this property to ‘latest’ will install the most updated version of WMF. Die einzigen derzeit möglichen Werte für diese Eigenschaft sind „4.0“, „5.0“ und „latest“.The only current possible values for this property are ‘4.0’, ‘5.0’, and ‘latest’. Diese möglichen Werte werden gelegentlich aktualisiert.These possible values are subject to updates. Der Standardwert ist „latest“.The default value is ‘latest’.
settings.configuration.urlsettings.configuration.url stringstring Gibt den URL-Speicherort an, von dem die ZIP-Datei Ihrer DSC-Konfiguration herunterzuladen ist.Specifies the URL location from which to download your DSC configuration zip file. Wenn die bereitgestellte URL ein SAS-Token für den Zugriff erfordert, müssen Sie die protectedSettings.configurationUrlSasToken-Eigenschaft auf den Wert Ihres SAS-Tokens festlegen.If the URL provided requires a SAS token for access, you will need to set the protectedSettings.configurationUrlSasToken property to the value of your SAS token. Diese Eigenschaft ist erforderlich, wenn „settings.configuration.script“ und/oder „settings.configuration.function“ definiert sind.This property is required if settings.configuration.script and/or settings.configuration.function are defined.
settings.configuration.scriptsettings.configuration.script stringstring Gibt den Dateinamen des Skripts an, das die Definition Ihrer DSC-Konfiguration enthält.Specifies the file name of the script that contains the definition of your DSC configuration. Dieses Skript muss sich im Stammverzeichnis der ZIP-Datei befinden, die von der durch die configuration.url-Eigenschaft angegebenen URL heruntergeladen wurde.This script must be in the root folder of the zip file downloaded from the URL specified by the configuration.url property. Diese Eigenschaft ist erforderlich, wenn „settings.configuration.url“ und/oder „settings.configuration.script“ definiert sind.This property is required if settings.configuration.url and/or settings.configuration.script are defined.
settings.configuration.functionsettings.configuration.function stringstring Gibt den Namen Ihrer DSC-Konfiguration an.Specifies the name of your DSC configuration. Die Konfiguration mit diesem Namen muss im Skript enthalten sein, das durch „configuration.script“ definiert ist.The configuration named must be contained in the script defined by configuration.script. Diese Eigenschaft ist erforderlich, wenn „settings.configuration.url“ und/oder „settings.configuration.function“ definiert sind.This property is required if settings.configuration.url and/or settings.configuration.function are defined.
settings.configurationArgumentssettings.configurationArguments CollectionCollection Definiert beliebige Parameter, die Sie Ihrer DSC-Konfiguration übergeben möchten.Defines any parameters you would like to pass to your DSC configuration. Diese Eigenschaft wird nicht verschlüsselt.This property will not be encrypted.
settings.configurationData.urlsettings.configurationData.url stringstring Gibt die URL an, unter der die Datei mit Ihren Konfigurationsdaten (.pds1) heruntergeladen werden kann, um sie als Eingabe für Ihre DSC-Konfiguration zu nutzen.Specifies the URL from which to download your configuration data (.pds1) file to use as input for your DSC configuration. Wenn die bereitgestellte URL ein SAS-Token für den Zugriff erfordert, müssen Sie die protectedSettings.configurationDataUrlSasToken-Eigenschaft auf den Wert Ihres SAS-Tokens festlegen.If the URL provided requires a SAS token for access, you will need to set the protectedSettings.configurationDataUrlSasToken property to the value of your SAS token.
settings.privacy.dataEnabledsettings.privacy.dataEnabled stringstring Aktiviert bzw. deaktiviert die Erfassung von Telemetriedaten.Enables or disables telemetry collection. Die einzig möglichen Werte für diese Eigenschaft sind „Enable“, „Disable“, „''“ oder „$null“.The only possible values for this property are ‘Enable’, ‘Disable’, ”, or $null. Wird die Eigenschaft leer gelassen oder „null“ angegeben, ist die Telemetrie aktiviert.Leaving this property blank or null will enable telemetry
settings.advancedOptions.forcePullAndApplysettings.advancedOptions.forcePullAndApply BoolBool Diese Einstellung ist dafür ausgelegt, die Arbeitserfahrung im Umgang mit der Erweiterung beim Registrieren von Knoten bei Azure Automation DSC zu verbessern.This setting is designed to enhance the experience of working with the extension to register nodes with Azure Automation DSC. Wenn der Wert auf $true festgelegt ist, wartet die Erweiterung die erste Ausführung der beim Dienst abgerufenen Konfiguration ab, bevor er die Erfolgs-/Fehlermeldung zurückgibt.If the value is $true, the extension will wait for the first run of the configuration pulled from the service before returning success/failure. Wenn der Wert auf „$false“ festgelegt ist, bezieht sich der von der Erweiterung zurückgegebene Status lediglich darauf, ob der Knoten erfolgreich bei Azure Automation State Configuration registriert wurde, und die Knotenkonfiguration wird während der Registrierung nicht ausgeführt.If the value is set to $false, the status returned by the extension will only refer to whether the node was registered with Azure Automation State Configuration successfully and the node configuration will not be run during the registration.
settings.advancedOptions.downloadMappingssettings.advancedOptions.downloadMappings CollectionCollection Definiert alternative Speicherorte zum Herunterladen von Abhängigkeiten wie WMF und .NET.Defines alternate locations to download dependencies such as WMF and .NET

Eigenschaftswerte geschützter EinstellungenProtected Settings Property values

NameName DatentypData Type BESCHREIBUNGDescription
protectedSettings.configurationArgumentsprotectedSettings.configurationArguments stringstring Definiert beliebige Parameter, die Sie Ihrer DSC-Konfiguration übergeben möchten.Defines any parameters you would like to pass to your DSC configuration. Diese Eigenschaft wird verschlüsselt.This property will be encrypted.
protectedSettings.configurationUrlSasTokenprotectedSettings.configurationUrlSasToken stringstring Gibt das SAS-Token für den Zugriff auf durch „configuration.url“ definierte URL an.Specifies the SAS token to access the URL defined by configuration.url. Diese Eigenschaft wird verschlüsselt.This property will be encrypted.
protectedSettings.configurationDataUrlSasTokenprotectedSettings.configurationDataUrlSasToken stringstring Gibt das SAS-Token für den Zugriff auf durch „configurationData.url“ definierte URL an.Specifies the SAS token to access the URL defined by configurationData.url. Diese Eigenschaft wird verschlüsselt.This property will be encrypted.

Bereitstellung von VorlagenTemplate deployment

Azure-VM-Erweiterungen können mithilfe von Azure Resource Manager-Vorlagen bereitgestellt werden.Azure VM extensions can be deployed with Azure Resource Manager templates. Vorlagen sind ideal, wenn Sie virtuelle Computer bereitstellen, die nach der Bereitstellung konfiguriert werden müssen.Templates are ideal when deploying one or more virtual machines that require post deployment configuration. Eine Resource Manager-Beispielvorlage mit der DSC-Erweiterung für Windows finden Sie im Azure-Schnellstartkatalog.A sample Resource Manager template that includes the DSC extension for Windows can be found on the Azure Quick Start Gallery.

Problembehandlung und SupportTroubleshoot and support

ProblembehandlungTroubleshoot

Daten zum Status von Erweiterungsbereitstellungen können über das Azure-Portal und mithilfe der Azure-Befehlszeilenschnittstelle abgerufen werden.Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure CLI. Führen Sie über die Azure-Befehlszeilenschnittstelle den folgenden Befehl aus, um den Bereitstellungsstatus von Erweiterungen für einen bestimmten virtuellen Computer anzuzeigen.To see the deployment state of extensions for a given VM, run the following command using the Azure CLI.

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

Das Erweiterungspaket wird an diesem Speicherort auf der Azure-VM heruntergeladen und bereitgestellt.Extension package is downloaded and deployed to this location on the Azure VM

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}

Die Statusdatei der Erweiterung enthält den untergeordneten Status und die Erfolgs-/Fehlercodes des Status zusammen mit der ausführlichen Fehlermeldung und einer Beschreibung für jede Erweiterungsausführung.Extension status file contains the sub status and status success/error codes along with the detailed error and description for each extension run.

C:\Packages\Plugins\{Extension_Name}\{Extension_Version}\Status\{0}.Status  -> {0} being the sequence number

Ausgabeprotokolle der Erweiterung werden im folgenden Verzeichnis protokolliert:Extension output logs are logged to the following directory:

C:\WindowsAzure\Logs\Plugins\{Extension_Name}\{Extension_Version}

Fehlercodes und ihre BedeutungError codes and their meanings

FehlercodeError Code BedeutungMeaning Mögliche AktionPossible Action
10001000 Allgemeiner FehlerGeneric error Die Nachricht für diesen Fehler wird durch die spezifische Ausnahme in Erweiterungsprotokollen bereitgestellt.The message for this error is provided by the specific exception in extension logs
5252 Fehler bei der Installation der ErweiterungExtension Install Error Die Nachricht für diesen Fehler wird durch die spezifische Ausnahme bereitgestellt.The message for this error is provided by the specific exception
10021002 Fehler bei der Installation von WMFWmf Install Error Dies ist ein Fehler bei der Installation von WMF.Error while installing WMF.
10041004 Ungültiges ZIP-PaketInvalid Zip Package Ungültige ZIP-Datei. Fehler beim Entpacken der ZIP-Datei.Invalid zip ; Error unpacking the zip
11001100 ArgumentfehlerArgument Error Weist auf ein Problem in der vom Benutzer bereitgestellten Eingabe hin.Indicates a problem in the input provided by the user. Die Nachricht für den Fehler wird durch die spezifische Ausnahme bereitgestellt.The message for the error is provided by the specific exception

SupportSupport

Sollten Sie beim Lesen dieses Artikels feststellen, dass Sie weitere Hilfe benötigen, können Sie sich über das MSDN Azure-Forum oder über das Stack Overflow-Forum mit Azure-Experten in Verbindung setzen.If you need more help at any point in this article, you can contact the Azure experts on the MSDN Azure and Stack Overflow forums. Alternativ dazu haben Sie die Möglichkeit, einen Azure-Supportfall zu erstellen.Alternatively, you can file an Azure support incident. Rufen Sie die Azure-Support-Website auf, und wählen Sie „Support erhalten“ aus.Go to the Azure support site and select Get support. Informationen zur Nutzung von Azure-Support finden Sie unter Microsoft Azure-Support-FAQ.For information about using Azure Support, read the Microsoft Azure support FAQ.