Estensione Script personalizzato per WindowsCustom Script Extension for Windows

L'estensione script personalizzata scarica ed esegue script sulle macchine virtuali di Azure.The Custom Script Extension downloads and executes scripts on Azure virtual machines. Questa estensione è utile per la configurazione post-distribuzione, l'installazione di software o qualsiasi altra attività di configurazione o gestione.This extension is useful for post deployment configuration, software installation, or any other configuration / management task. Gli script possono essere scaricati dall'archiviazione di Azure o da GitHub, oppure possono essere forniti al portale di Azure durante il runtime dell'estensione.Scripts can be downloaded from Azure storage or GitHub, or provided to the Azure portal at extension run time. L'estensione script personalizzata è integrabile nei modelli di Azure Resource Manager e può essere eseguita anche tramite l'interfaccia della riga di comando di Azure, PowerShell, il portale di Azure o l'API REST di Macchine virtuali di Azure.The Custom Script extension integrates with Azure Resource Manager templates, and can also be run using the Azure CLI, PowerShell, Azure portal, or the Azure Virtual Machine REST API.

Questo documento descrive come usare l'estensione di script personalizzata con il modulo Azure PowerShell e i modelli di Azure Resource Manager e inoltre illustra i passaggi per la risoluzione dei problemi nei sistemi Windows.This document details how to use the Custom Script Extension using the Azure PowerShell module, Azure Resource Manager templates, and details troubleshooting steps on Windows systems.

PrerequisitiPrerequisites

Sistema operativoOperating System

L'estensione di script personalizzata per Windows può essere eseguita in Windows 10 Client, Windows Server 2008 R2, 2012, 2012 R2 e 2016.The Custom Script Extension for Windows can be run against Windows 10 Client, Windows Server 2008 R2, 2012, 2012 R2, and 2016 releases.

Percorso dello scriptScript Location

Lo script deve essere archiviato nell'archiviazione BLOB di Azure o in un altro percorso accessibile tramite un URL valido.The script needs to be stored in Azure Blob storage, or any other location accessible through a valid URL.

Connettività InternetInternet Connectivity

Per distribuire l'estensione di script personalizzata per Windows, è necessario che la macchina virtuale di destinazione sia connessa a Internet.The Custom Script Extension for Windows requires that the target virtual machine is connected to the internet.

Schema dell'estensioneExtension schema

Il codice JSON seguente mostra lo schema dell'estensione di script personalizzata.The following JSON shows the schema for the Custom Script Extension. L'estensione richiede un percorso dello script (archiviazione di Azure o altro percorso con un URL valido) e un comando da eseguire.The extension requires a script location (Azure Storage or other location with valid URL), and a command to execute. Se si usa l'archiviazione di Azure come origine dello script, sono necessari un nome e una chiave di account.If using Azure Storage as the script source, an Azure storage account name and account key is required. Questi elementi devono essere trattati come dati sensibili ed essere specificati nella configurazione protetta dell'estensione.These items should be treated as sensitive data and specified in the extensions protected setting configuration. I dati della configurazione protetta dell'estensione macchina virtuale di Azure vengono crittografati, per essere poi decrittografati solo nella macchina virtuale di destinazione.Azure VM extension protected setting data is encrypted, and only decrypted on the target virtual machine.

{
    "apiVersion": "2015-06-15",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "name": "config-app",
    "location": "[resourceGroup().location]",
    "dependsOn": [
        "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'),copyindex())]",
        "[variables('musicstoresqlName')]"
    ],
    "tags": {
        "displayName": "config-app"
    },
    "properties": {
        "publisher": "Microsoft.Compute",
        "type": "CustomScriptExtension",
        "typeHandlerVersion": "1.9",
        "autoUpgradeMinorVersion": true,
        "settings": {
            "fileUris": [
                "script location"
            ]
        },
        "protectedSettings": {
            "commandToExecute": "myExecutionCommand",
            "storageAccountName": "myStorageAccountName",
            "storageAccountKey": "myStorageAccountKey"
        }
    }
}

Valori delle proprietàProperty values

NomeName Valore/EsempioValue / Example
apiVersionapiVersion 2015-06-152015-06-15
publisherpublisher Microsoft.ComputeMicrosoft.Compute
typetype Estensioniextensions
typeHandlerVersiontypeHandlerVersion 1.91.9
fileUris (es.)fileUris (e.g) https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1
commandToExecute (es.)commandToExecute (e.g) powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1
storageAccountName (es.)storageAccountName (e.g) examplestorageacctexamplestorageacct
storageAccountKey (es.)storageAccountKey (e.g) TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==

Nota: questi nomi di proprietà fanno distinzione tra maiuscole e minuscole.Note - these property names are case sensitive. Usare i nomi come sono riportati sopra per evitare problemi di distribuzione.Use the names as seen above to avoid deployment issues.

Distribuzione del modelloTemplate deployment

Le estensioni macchina virtuale di Azure possono essere distribuite con i modelli di Azure Resource Manager.Azure VM extensions can be deployed with Azure Resource Manager templates. Lo schema JSON indicato nella sezione precedente può essere usato in un modello di Azure Resource Manager per eseguire l'estensione di script personalizzata durante la distribuzione di un modello di Azure Resource Manager.The JSON schema detailed in the previous section can be used in an Azure Resource Manager template to run the Custom Script Extension during an Azure Resource Manager template deployment. Un modello di esempio che include l'estensione script personalizzata è disponibile su GitHub.A sample template that includes the Custom Script Extension can be found here, GitHub.

Distribuzione PowerShellPowerShell deployment

Il comando Set-AzureRmVMCustomScriptExtension consente di aggiungere l'estensione di script personalizzata a una macchina virtuale esistente.The Set-AzureRmVMCustomScriptExtension command can be used to add the Custom Script extension to an existing virtual machine. Per ulteriori informazioni, vedere Set-AzureRmVMCustomScriptExtension.For more information, see Set-AzureRmVMCustomScriptExtension .

Set-AzureRmVMCustomScriptExtension -ResourceGroupName myResourceGroup `
    -VMName myVM `
    -Location myLocation `
    -FileUri myURL `
    -Run 'myScript.ps1' `
    -Name DemoScriptExtension

Risoluzione dei problemi e supportoTroubleshoot and support

Risolvere problemiTroubleshoot

I dati sullo stato delle distribuzioni dell'estensione possono essere recuperati nel portale di Azure e tramite il modulo Azure PowerShell.Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure PowerShell module. Per visualizzare lo stato di distribuzione delle estensioni per una determinata macchina virtuale, eseguire il comando seguente.To see the deployment state of extensions for a given VM, run the following command.

Get-AzureRmVMExtension -ResourceGroupName myResourceGroup -VMName myVM -Name myExtensionName

L'output dell'esecuzione dell'estensione viene registrato nei file presenti nella directory seguente nella macchina virtuale di destinazione.Extension execution output is logged to files found under the following directory on the target virtual machine.

C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension

I file specificati vengono scaricati nella directory seguente nella macchina virtuale di destinazione.The specified files are downloaded into the following directory on the target virtual machine.

C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.*\Downloads\<n>

dove <n> è un numero intero decimale che può variare nelle diverse esecuzioni dell'estensione.where <n> is a decimal integer which may change between executions of the extension. Il valore 1.* corrisponde al valore effettivo attuale typeHandlerVersion dell'estensione.The 1.* value matches the actual, current typeHandlerVersion value of the extension. Ad esempio, la directory effettiva potrebbe essere C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.For example, the actual directory could be C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.

Quando si esegue il comando commandToExecute, nell'estensione sarà impostata questa directory (ad esempio ...\Downloads\2) come directory di lavoro attuale.When executing the commandToExecute command, the extension will have set this directory (e.g., ...\Downloads\2) as the current working directory. In questo modo viene abilitato l'uso di percorsi relativi per individuare i file scaricati tramite la proprietà fileURIs.This enables the use of relative paths to locate the files downloaded via the fileURIs property. Nella tabella seguente sono riportati alcuni esempi.See the table below for examples.

Poiché il percorso di download assoluto può variare nel tempo, quando è possibile è preferibile optare per percorsi relativi di script/file nella stringa commandToExecute.Since the absolute download path may vary over time, it is better to opt for relative script/file paths in the commandToExecute string, whenever possible. Ad esempio:For example:

    "commandToExecute": "powershell.exe . . . -File './scripts/myscript.ps1'"

Le informazioni sul percorso dopo il primo segmento URI vengono mantenute per i file scaricati tramite l'elenco delle proprietà fileUris.Path information after the first URI segment is retained for files downloaded via the fileUris property list. Come illustrato nella tabella riportata di seguito, per i file scaricati viene eseguito il mapping nelle sottodirectory di download per riflettere la struttura dei valori fileUris.As shown in the table below, downloaded files are mapped into download subdirectories to reflect the structure of the fileUris values.

Esempi di file scaricatiExamples of Downloaded Files

URI in fileUrisURI in fileUris Percorso relativo scaricatoRelative downloaded location Percorso assoluto scaricato *Absolute downloaded location *
https://someAcct.blob.core.windows.net/aContainer/scripts/myscript.ps1 ./scripts/myscript.ps1 C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\scripts\myscript.ps1
https://someAcct.blob.core.windows.net/aContainer/topLevel.ps1 ./topLevel.ps1 C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\topLevel.ps1

* Come in precedenza, i percorsi assoluti delle directory cambieranno nella durata della macchina virtuale ma non all'interno di una singola esecuzione dell'estensione CustomScript.* As above, the absolute directory paths will change over the lifetime of the VM, but not within a single execution of the CustomScript extension.

SupportoSupport

Per ricevere maggiore assistenza in qualsiasi punto di questo articolo, contattare gli esperti di Azure nei [forum di Azure su MSDN e Stack Overflow].(https://azure.microsoft.com/en-us/support/forums/).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. In alternativa, è possibile archiviare un evento imprevisto di supporto tecnico di Azure.Alternatively, you can file an Azure support incident. Accedere al sito del supporto di Azure e selezionare l'opzione desiderata per ottenere supporto.Go to the Azure support site and select Get support. Per informazioni sull'uso del supporto di Azure, leggere le Domande frequenti sul supporto di Azure.For information about using Azure Support, read the Microsoft Azure support FAQ.