Verwenden der Konfigurationsklassen
Aktualisiert: November 2007
Die meisten Konfigurationsarbeiten werden mit der Configuration-Klasse durchgeführt. Diese Klasse stellt Konfigurationen von Computern, .NET-Clientanwendungen, ASP.NET-Anwendungen, Webverzeichnissen und Ressourcen dar, die in Webverzeichnissen gespeichert sind.
In ASP.NET, Version 2.0, können Sie Zugriff auf eine Instanz der Configuration-Klasse erhalten, indem Sie die Methoden des WebConfigurationManager-Objekts verwenden, um einen Konfigurationsabschnitt abzurufen. (In .NET Framework-Clientanwendungen können Sie das ähnliche ConfigurationManager-Objekt verwenden). Jeder Konfigurationsabschnitt verfügt über einen eigenen Objekttyp, der in den Referenzthemen unter ASP.NET-Konfigurationseinstellungen in der Tabelle "Elementinformationen" als Abschnittshandler aufgelistet ist. Ein Beispiel finden Sie unter Gewusst wie: Programmgesteuerter Zugriff auf die ASP.NET-Konfigurationseinstellungen.
In den folgenden Abschnitten ist beschrieben, wie die Konfigurationsklassen in verschiedenen Szenarios verwendet werden. Eine Zusammenfassung der Konfigurationsklassen finden Sie unter Übersicht über die ASP.NET-Konfigurations-API.
In allen unten angegebenen Beispielen werden die nicht statische Configuration.GetSection-Methode und die nicht statische Configuration.GetSectionGroup-Methode verwendet, indem zuerst eine Instanz der System.Configuration.Configuration-Klasse erstellt wird. Dies ermöglicht es Ihnen, Konfigurationsinformationen aus einer beliebigen Anwendung abzurufen. Verwenden Sie zum Abrufen von Konfigurationsdaten aus der Anwendung, in der sich Ihr Code befindet, die statischen GetSection-Methoden, da diese schneller verarbeitet werden. Weitere Informationen finden Sie im Abschnitt "Arbeiten mit lokalen und Remotekonfigurationseinstellungen" unter Übersicht über die ASP.NET-Konfigurations-API.
Öffnen eines den globalen Konfigurationseinstellungen zugeordneten Konfigurationsobjekts
Um eine Konfigurationsdatei für die globale Konfiguration zu öffnen, ruft Ihre Anwendung die statische OpenMachineConfiguration-Methode der WebConfigurationManager-Klasse auf. Im folgenden Codebeispiel öffnet die OpenMachineConfiguration-Methode das Konfigurationsobjekt, das mit der Datei Machine.config in .NET Framework 2.0 übereinstimmt, und gibt dieses zurück. Mithilfe anderer Versionen dieser überladenen Methode können Sie einen Speicherort, einen Remoteserver oder Benutzerinformationen angeben.
' Obtains the machine configuration settings on the local machine.
Dim machineConfig As System.Configuration.Configuration
machineConfig = _
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration()
machineConfig.SaveAs("c:\machineConfig.xml")
// Obtains the machine configuration settings on the local machine.
System.Configuration.Configuration machineConfig =
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration();
machineConfig.SaveAs("c:\\machineConfig.xml");
Die Konfigurations-API ist versionsspezifisch. Daher ist es nicht möglich, die Datei Machine.config für eine Version von .NET Framework zu öffnen, indem Sie die Methoden einer anderen Version von .NET Framework verwenden.
Erforderliche Berechtigungen
Die Anwendung benötigt eine Leseberechtigung für die physikalische Datei Machine.config, um die Computerkonfigurationsdatei öffnen zu können. Um die Computerkonfiguration ändern zu können, benötigt die Anwendung eine Schreibberechtigung für die Datei und eine Erstellungsberechtigung für das .NET Framework-Konfigurationsverzeichnis.
Öffnen eines Konfigurationsobjekts, das Webanwendungs-Konfigurationseinstellungen zugeordnet ist
Um eine Konfigurationsdatei für eine Webanwendung zu öffnen, ruft die Anwendung die statische OpenWebConfiguration-Methode der WebConfigurationManager-Klasse auf und übergibt dabei den relativen Pfad des zu öffnenden virtuellen IIS (Internetinformationsdienste)-Verzeichnisses.
Die Werte des Pfadparameters können vom IIS-Metabasispfad des Verzeichnisses abgerufen werden, das die erforderliche Konfiguration enthält. Wenn der IIS-Metabasispfad z. B. W3SVC/1/Root/Temp lautet, ist der Pfad /Temp, da die Standardsite 1 ist.
Im folgenden Codebeispiel öffnet die OpenWebConfiguration-Methode das Konfigurationsobjekt, das der temporären Webanwendung in der Standardwebsite entspricht, und gibt dieses zurück. Das Konfigurationsobjekt enthält Konfigurationseinstellungen, die lokal in einer Web.config-Datei angegeben sind, sowie alle geerbten Einstellungen von übergeordneten Konfigurationsdateien bis hin zur Datei Machine.config. Mithilfe anderer Versionen dieser überladenen Methode können Sie eine Website, einen Speicherort, einen Remoteserver und Benutzerinformationen angeben.
' Obtains the configuration settings for a Web application.
Dim webConfig As System.Configuration.Configuration
webConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
webConfig.SaveAs("c:\\webConfig.xml")
// Obtains the configuration settings for a Web application.
System.Configuration.Configuration webConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
webConfig.SaveAs("c:\\webConfig.xml");
Ein System.Configuration.Configuration-Objekt kann auch dann geöffnet werden, wenn keine physikalische Web.config-Datei vorhanden ist. In diesem Fall besteht die zurückgegebene Konfiguration vollständig aus Einstellungen, die aus der Konfigurationsdateihierarchie geerbt wurden. Weitere Informationen hierzu finden Sie unter ASP.NET-Konfigurationsszenarios.
Erforderliche Berechtigungen
Um eine Webkonfigurationsdatei öffnen zu können, benötigt die Anwendung eine Leseberechtigung für die physikalische Web.config-Datei sowie für alle ihr übergeordneten Dateien in der Hierarchie.
Öffnen eines Konfigurationsobjekts, das einem Abschnitt in einer Konfigurationsdatei zugeordnet ist
Um Konfigurationsinformationen aus einem Abschnitt abzurufen, ruft die Anwendung die nicht statische GetSectionGroup-Methode der Configuration-Klasse auf und übergibt den Abschnittsnamen. Für Abschnitte, die in Abschnittsgruppen enthalten sind, können Sie entweder einen XPath zum Abschnitt (system.web/anonymousIdentification) verwenden oder ein Konfigurationsobjekt abrufen, das der Abschnittsgruppe zunächst zugeordnet ist. Eine Liste von Abschnittsnamen finden Sie unter ASP.NET-Konfigurationseinstellungen.
Im folgenden Codebeispiel öffnet die OpenWebConfiguration-Methode das Konfigurationsobjekt, das der temporären Webanwendung in der Standardwebsite entspricht, gibt dieses zurück und verwendet das Objekt dann zum Abrufen eines Verweises auf die system.web-Abschnittsgruppe, mit deren Hilfe dann ein Verweis auf den anonymousIdentification-Abschnitt abgerufen wird.
' Obtains the configuration settings for the <anonymousIdentification> section.
Dim config As System.Configuration.Configuration
config = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
Dim systemWeb As System.Web.Configuration.SystemWebSectionGroup
systemWeb = config.GetSectionGroup("system.web")
Dim sectionConfig As System.Web.Configuration.AnonymousIdentificationSection
sectionConfig = systemWeb.AnonymousIdentification
Dim sb As New StringBuilder
sb.AppendLine("<anonymousIdentification> attributes:")
Dim props As System.Configuration.PropertyInformationCollection
props = sectionConfig.ElementInformation.Properties
For Each prop As System.Configuration.PropertyInformation In props
sb.Append(prop.Name.ToString())
sb.Append(" = ")
sb.AppendLine(prop.Value.ToString())
Next
Console.WriteLine(sb.ToString())
// Obtains the configuration settings for the <anonymousIdentification> section.
System.Configuration.Configuration config =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
System.Web.Configuration.SystemWebSectionGroup systemWeb =
config.GetSectionGroup("system.web")
as System.Web.Configuration.SystemWebSectionGroup;
System.Web.Configuration.AnonymousIdentificationSection sectionConfig =
systemWeb.AnonymousIdentification;
if (null != sectionConfig)
{
StringBuilder sb = new StringBuilder();
sb.Append("<anonymousIdentification> attributes:\r\n");
System.Configuration.PropertyInformationCollection props =
sectionConfig.ElementInformation.Properties;
foreach (System.Configuration.PropertyInformation prop in props)
{
sb.AppendFormat("{0} = {1}\r\n", prop.Name.ToString(), prop.Value.ToString());
}
Console.WriteLine(sb.ToString());
}
Ein System.Configuration.Configuration-Objekt kann auch dann geöffnet werden, wenn keine physikalische Web.config-Datei vorhanden ist. In diesem Fall besteht die zurückgegebene Konfiguration vollständig aus Einstellungen, die aus der Konfigurationsdateihierarchie geerbt wurden. Weitere Informationen hierzu finden Sie unter ASP.NET-Konfigurationsszenarios.
Erforderliche Berechtigungen
Um einen Abschnitt in einer Webkonfigurationsdatei öffnen zu können, benötigt die Anwendung eine Leseberechtigung für die physikalische Web.config-Datei und für alle ihr übergeordneten Dateien in der Hierarchie. Anwendungen mit verwaltetem Code benötigen entsprechende Berechtigungen, um Systemabschnitte lesen zu können. Anwendungen mit voller und hoher Vertrauenswürdigkeit verfügen standardmäßig über diese Berechtigungen. Anders ausgedrückt können Anwendungen mit mittlerer oder niedriger Vertrauenswürdigkeit standardmäßig keine Konfigurationsabschnitte lesen.
Öffnen eines den Remotekonfigurationseinstellungen zugeordneten Konfigurationsobjekts
Sie können die Konfigurations-API verwenden, um die Konfiguration eines Remotecomputers zu öffnen. Die API kann die Computerkonfigurationsdatei eines anderen Computers oder die Anwendungskonfigurationsdatei einer beliebigen IIS-Anwendung oder ihre Unterverzeichnisse öffnen.
Um eine Computerkonfigurationsdatei auf einem anderen Computer zu öffnen, ruft die Anwendung die statische OpenMachineConfiguration-Methode auf und übergibt den Namen des Servers.
Um eine Web.config-Datei auf einem anderen Computer zu öffnen, ruft die Anwendung die statische OpenWebConfiguration-Methode auf und übergibt den (zur Website) relativen Pfad an das Konfigurationsobjekt, den Websitebezeichner und den Namen des Servers. Das zurückgegebene Konfigurationsobjekt enthält Konfigurationseinstellungen, die lokal in einer Web.config-Datei angegeben sind, und alle geerbten Einstellungen von übergeordneten Konfigurationsdateien bis hin zur Datei Machine.config.
Servernamen sind gültige Namen von Windows-Netzwerkcomputern. Diese Namen werden von ASP.NET nicht besonders behandelt, sondern direkt an das Betriebssystem übergeben.
In den folgenden Codebeispielen wird veranschaulicht, wie eine Computerkonfiguration, die Stammkonfiguration einer Standardsite und eine Webkonfiguration in einem Anwendungsverzeichnis geöffnet werden.
Dim userToken As IntPtr
userToken = System.Security.Principal.WindowsIdentity.GetCurrent().Token
' Obtains the machine configuration settings on a remote machine.
Dim remoteMachineConfig As System.Configuration.Configuration
remoteMachineConfig = _
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration( _
Nothing, "JanetFi2", userToken)
remoteMachineConfig.SaveAs("c:\remoteMachineConfig.xml")
' Obtains the root Web configuration settings on a remote machine.
Dim remoteRootConfig As System.Configuration.Configuration
remoteRootConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration( _
Nothing, Nothing, Nothing, "JanetFi2", userToken)
remoteRootConfig.SaveAs("c:\remoteRootConfig.xml")
' Obtains the configuration settings for the
' W3SVC/1/Root/Temp application on a remote machine.
Dim remoteWebConfig As System.Configuration.Configuration
remoteWebConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration( _
"/Temp", "1", Nothing, "JanetFi2", userToken)
remoteWebConfig.SaveAs("c:\\remoteWebConfig.xml")
IntPtr userToken = System.Security.Principal.WindowsIdentity.GetCurrent().Token;
// Obtains the machine configuration settings on a remote machine.
System.Configuration.Configuration remoteMachineConfig =
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration
(null, "ServerName", userToken);
remoteMachineConfig.SaveAs("c:\\remoteMachineConfig.xml");
// Obtains the root Web configuration settings on a remote machine.
System.Configuration.Configuration remoteRootConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration
(null, null, null, "ServerName", userToken);
remoteRootConfig.SaveAs("c:\\remoteRootConfig.xml");
// Obtains the configuration settings for the
// W3SVC/1/Root/Temp application on a remote machine.
System.Configuration.Configuration remoteWebConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration
("/Temp", "1", null, "ServerName", userToken);
remoteWebConfig.SaveAs("c:\\remoteWebConfig.xml");
Erforderliche Berechtigungen
Um eine Konfigurationsdatei auf einem Remotecomputer zu öffnen, muss die Anwendung über Administratorrechte für den Remotecomputer verfügen. Diese Anforderung ist restriktiver als die Anforderung für die lokale Verwendung. Für lokale Konfigurationsdateien benötigt die Anwendung lediglich Leserechte für die Konfigurationsdateien in der Hierarchie und für die IIS-Metabasis (um die IIS-Pfade aufzulösen).
Führen Sie das Tool Aspnet_regiis.exe mit dem "-config+"-Parameter auf dem Remotecomputer aus, bevor Sie mit der Konfiguration beginnen. Weitere Informationen finden Sie unter ASP.NET IIS-Registrierungstool (Aspnet_regiis.exe).
Aktualisieren der Konfigurationseinstellungen
Zum Aktualisieren eines geöffneten Konfigurationsobjekts ruft die Anwendung die Save-Methode oder die SaveAs-Methode des Konfigurationsobjekts auf. Diese Methoden schreiben alle Änderungen der Konfigurationseinstellungen für dieses Objekt. Wenn am Speicherort keine Konfigurationsdatei vorhanden ist, wird eine neue Konfigurationsdatei erstellt.
Im folgenden Codebeispiel wird das debug-Attribut des compilation-Abschnitts auf true festgelegt.
' Updates the configuration settings for a Web application.
Dim updateWebConfig As System.Configuration.Configuration
updateWebConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
Dim compilation As System.Web.Configuration.CompilationSection
compilation = _
updateWebConfig.GetSection("system.web/compilation")
Console.WriteLine("Current <compilation> debug = {0}", compilation.Debug)
compilation.Debug = True
If Not compilation.SectionInformation.IsLocked Then
updateWebConfig.Save()
Console.WriteLine("New <compilation> debug = {0}", compilation.Debug)
Else
Console.WriteLine("Could not save configuration.")
End If
// Updates the configuration settings for a Web application.
System.Configuration.Configuration updateWebConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
System.Web.Configuration.CompilationSection compilation =
updateWebConfig.GetSection("system.web/compilation")
as System.Web.Configuration.CompilationSection;
Console.WriteLine("Current <compilation> debug = {0}", compilation.Debug);
compilation.Debug = true;
if (!compilation.SectionInformation.IsLocked)
{
updateWebConfig.Save();
Console.WriteLine("New <compilation> debug = {0}", compilation.Debug);
}
else
{
Console.WriteLine("Could not save configuration.");
}
Derzeit gibt es keine Funktion, mit der Konfigurationsdaten während der Aktualisierung gesperrt werden können. Daher verwendet die Konfigurations-API zum Ändern der Konfiguration ein Modell, das von vollständiger Parallelität ausgeht. Wenn zwei Anwendungen in diesem Modell gleichzeitig dieselbe Konfiguration öffnen, erhalten sie eigene Kopien des Konfigurationsobjekts. Wenn eine Anwendung versucht, die Konfiguration zu ändern, indem sie die Save-Methode oder die SaveAs-Methode aufruft, und die zugrunde liegende Konfigurationsdatei geändert wurde, seit die Anwendung das Konfigurationsobjekt abgerufen hat, löst die Methode eine Ausnahme aus. Die zugrunde liegende Datei könnte von einer anderen Anwendung, die die Konfiguration aktualisiert hat, oder durch eine andere von der Konfigurations-API unabhängige Änderung geändert worden sein.
Erforderliche Berechtigungen
Um eine Webkonfiguration ändern zu können, benötigt die Anwendung eine Schreibberechtigung für die Datei und eine Erstellungsberechtigung für das Verzeichnis, in dem die Datei enthalten ist.
Siehe auch
Konzepte
Übersicht über die ASP.NET-Konfigurations-API