Documento <predefinitoDocumento predefinito>

  • Articolo

Panoramica

L'elemento <defaultDocument> consente di abilitare o disabilitare il comportamento predefinito del documento per il sito Web o l'applicazione. Questo elemento contiene un elemento figlio che contiene un <files> insieme di <add> elementi. Ogni <add> elemento definisce i documenti predefiniti restituiti dal sito o dall'applicazione a un browser client quando il sito riceve una richiesta alla directory radice.

L'elemento <defaultDocument> può contenere anche uno o più <remove> elementi. Ogni <remove> elemento rimuove un file di documento predefinito specifico ereditato da un file di configurazione di livello superiore nel server Internet Information Services (IIS) 7. È anche possibile usare l'elemento <clear> per rimuovere tutte le impostazioni predefinite del documento definite più in alto nella gerarchia di configurazione.

I documenti predefiniti sono abilitati per impostazione predefinita e IIS 7 definisce i seguenti file di documento predefiniti nel file ApplicationHost.config come impostazione predefinita a livello di server:

  • Default.htm
  • Default.asp
  • Index.htm
  • Index.html
  • Iisstart.htm

Se si installa ASP.NET nel server Web, il processo di installazione aggiungerà il file Default.aspx a questo elenco.

Per impostazione predefinita, quando una richiesta arriva per la directory radice del sito o dell'applicazione, IIS 7 invia una risposta al browser in base ai nomi di file definiti nell'elemento <defaultDocument> . IIS tenta di restituire i file corretti nell'ordine in cui vengono visualizzati nell'elemento <defaultDocument> . Se il file Default.htm esiste, IIS lo invia al browser client. Se il file Default.htm non esiste, IIS tenta di inviare il file Default.asp al browser e, se il file Default.asp non esiste, IIS tenta di inviare il file Index.htm al browser. IIS continua in questo modo finché non tenta di inviare ogni file di documento predefinito al browser client.

Nota

Se si ordina correttamente questo elenco di documenti predefiniti, è possibile migliorare le prestazioni di IIS. Ad esempio, se si intende usare Index.php per la home page in tutte le cartelle del sito Web e si aggiunge Index.php nella parte inferiore dell'elenco dei documenti predefiniti, IIS dovrà verificare la presenza di ognuno dei documenti predefiniti nell'elenco prima di tentare di restituire Index.php al browser client. A seconda del numero di cartelle nel sito Web e del numero di richieste del browser client, ciò potrebbe influire sulle prestazioni.

Se si disabilitano i documenti predefiniti ma è stato abilitato l'esplorazione della directory, IIS restituisce un elenco di directory quando una richiesta per la directory radice arriva da un browser. Se si disabilitano sia i documenti predefiniti che l'esplorazione della directory, IIS invia un errore "HTTP 404 File Non esiste" nel browser.

Compatibilità

Versione Note
IIS 10.0 L'elemento <defaultDocument> non è stato modificato in IIS 10.0.
IIS 8,5 L'elemento <defaultDocument> non è stato modificato in IIS 8.5.
IIS 8,0 L'elemento <defaultDocument> non è stato modificato in IIS 8.0.
IIS 7,5 L'elemento <defaultDocument> non è stato modificato in IIS 7.5.
IIS 7.0 L'elemento <defaultDocument> è stato introdotto in IIS 7.0.
IIS 6.0 L'elemento <defaultDocument> sostituisce la proprietà DefaultDoc iis 6.0 e il valore EnableDefaultDoc della proprietà DirBrowseFlags nell'oggetto metabase IIsWebService .

Installazione

L'elemento <defaultDocument> è incluso nell'installazione predefinita di IIS 7.

Procedure

Come aggiungere un documento predefinito per un'applicazione o un sito

  1. Aprire Gestione Internet Information Services (IIS):

    • Se si usa Windows Server 2012 o Windows Server 2012 R2:

      • Nella barra delle applicazioni fare clic su Server Manager, scegliere Strumenti e quindi fare clic su Gestione Internet Information Services (IIS).

    • Se si usa Windows 8 o Windows 8.1:

      • Tenere premuto il tasto Windows, premere la lettera X e quindi fare clic su Pannello di controllo.
      • Fare clic su Strumenti di amministrazione e quindi fare doppio clic su Gestione Internet Information Services (IIS).

    • Se si usa Windows Server 2008 o Windows Server 2008 R2:

      • Nella barra delle applicazioni fare clic su Start, scegliere Strumenti di amministrazione e quindi fare clic su Gestione Internet Information Services (IIS).

    • Se si usa Windows Vista o Windows 7:

      • Nella barra delle applicazioni fare clic su Start e quindi fare clic su Pannello di controllo.
      • Fare doppio clic su Strumenti di amministrazione e quindi fare doppio clic su Gestione Internet Information Services (IIS).

  2. Nel riquadro Connessioni espandere il nome del server, espandere Siti e quindi passare al sito Web o all'applicazione in cui si desidera configurare i documenti predefiniti.

  3. Nel riquadro Home fare doppio clic su Documento predefinito.
    Screenshot del riquadro Home con l'opzione Documento predefinito evidenziata.

  4. Nel riquadro Azioni fare clic su Aggiungi...

  5. Nella finestra di dialogo Aggiungi documento predefinito digitare il nome del documento predefinito da aggiungere nella casella Nome e quindi fare clic su OK.
    Screenshot della finestra di dialogo Aggiungi documento predefinito.

  6. Se necessario, nel riquadro Azioni selezionare un documento predefinito nell'elenco e quindi fare clic su Sposta su o Sposta verso il basso per definire l'ordine in cui IIS deve eseguire la ricerca nell'elenco dei documenti predefinito.

  7. Nella casella Avviso documento predefinito fare clic su Sì per rifiutare l'ereditarietà di configurazione da un livello di configurazione padre oppure fare clic su No o Annulla per annullare la modifica nell'ordine di documento predefinito.
    Screenshot della casella di avviso Documento predefinito con lo stato attivo sull'opzione Sì.

  8. Se necessario, fare clic su Rimuovi nel riquadro Azioni per rimuovere eventuali nomi di file che non si desidera usare come documenti predefiniti.

Configurazione

È possibile modificare l'ordine in cui IIS elabora i documenti predefiniti modificando l'ordine degli <add> elementi nell'elemento <defaultDocument> .

È possibile configurare l'elemento <defaultDocument> a livello di server nel file ApplicationHost.config e a livello di sito, applicazione o URL nel file di Web.config appropriato.

Attributi

Attributo Descrizione
enabled Attributo booleano facoltativo.

Specifica che i documenti predefiniti sono abilitati.

Il valore predefinito è true.

Elementi figlio

Elemento Descrizione
files Elemento facoltativo.

Specifica un elenco di nomi di file che possono essere restituiti come documenti predefiniti.

Esempio di configurazione

L'esempio di configurazione seguente, quando incluso in un file di Web.config per un sito o un'applicazione, abilita i documenti predefiniti per il sito o l'applicazione. Aggiunge quindi il nome del file "Home.html" all'elenco dei documenti predefiniti del sito o dell'applicazione.

<configuration>
   <system.webServer>
      <defaultDocument enabled="true">
         <files>
            <add value="home.html" />
         </files>
      </defaultDocument>
   </system.webServer>
</configuration>

Codice di esempio

Gli esempi seguenti abilitano i documenti predefiniti in un sito Web denominato Contoso e quindi aggiungono un file denominato Home.html all'elenco dei documenti predefiniti per il sito.

AppCmd.exe

appcmd.exe set config "Contoso" /section:defaultDocument /enabled:true /+files.[value='home.html']

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample {

    private static void Main() {
        
        using(ServerManager serverManager = new ServerManager()) { 
            Configuration config = serverManager.GetWebConfiguration("Contoso");
            
            ConfigurationSection defaultDocumentSection = config.GetSection("system.webServer/defaultDocument");
            
            defaultDocumentSection["enabled"] = true;
            
            ConfigurationElementCollection filesCollection = defaultDocumentSection.GetCollection("files");
            ConfigurationElement addElement = filesCollection.CreateElement("add");
            addElement["value"] = @"home.html";
            filesCollection.AddAt(0, addElement);
            
            serverManager.CommitChanges();
        }
    }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Class Sample
   Shared Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetWebConfiguration("Contoso")
      Dim defaultDocumentSection As ConfigurationSection = config.GetSection("system.webServer/defaultDocument")

      defaultDocumentSection("enabled") = True

      Dim filesCollection As ConfigurationElementCollection = defaultDocumentSection.GetCollection("files")
      Dim addElement As ConfigurationElement = filesCollection.CreateElement("add")
      addElement("value") = "home.html"
      filesCollection.AddAt(0, addElement)

      serverManager.CommitChanges()
   End Sub
End Class

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso";

var defaultDocumentSection = adminManager.GetAdminSection("system.webServer/defaultDocument",
   "MACHINE/WEBROOT/APPHOST/Contoso");

defaultDocumentSection.Properties.Item("enabled").Value = true;

var filesCollection = defaultDocumentSection.ChildElements.Item("files").Collection;

var addElement = filesCollection.CreateNewElement("add");
addElement.Properties.Item("value").Value = "home.html";
filesCollection.AddElement(addElement, 0);

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso"

Set defaultDocumentSection = adminManager.GetAdminSection("system.webServer/defaultDocument", _
   "MACHINE/WEBROOT/APPHOST/Contoso")

defaultDocumentSection.Properties.Item("enabled").Value = True  

Set filesCollection = defaultDocumentSection.ChildElements.Item("files").Collection

Set addElement = filesCollection.CreateNewElement("add")
addElement.Properties.Item("value").Value = "home.html"
filesCollection.AddElement addElement, 0

adminManager.CommitChanges