Ekinlikler
31 Mar 23 - 2 Nis 23
Microsoft Fabric, Power BI, SQL ve yapay zeka topluluğu tarafından yönetilen nihai etkinlik. 31 Mart - 2 Nisan 2025.
Bugün kaydolunBu tarayıcı artık desteklenmiyor.
En son özelliklerden, güvenlik güncelleştirmelerinden ve teknik destekten faydalanmak için Microsoft Edge’e yükseltin.
Stephen Molloy ve Rick Anderson tarafından
Yapılandırma oluşturucuları, ASP.NET uygulamaların dış kaynaklardan yapılandırma değerlerini alması için modern ve çevik bir mekanizma sağlar.
Yapılandırma oluşturucuları:
Yapılandırma oluşturucuları tarafından işlenebilen yaygın bir senaryo, bir anahtar/değer deseni izleyen yapılandırma bölümleri için temel bir anahtar/değer değiştirme mekanizması sağlamaktır. ConfigurationBuilders'ın .NET Framework kavramı belirli yapılandırma bölümleri veya desenleriyle sınırlı değildir. Ancak içindeki yapılandırma oluşturucularının Microsoft.Configuration.ConfigurationBuilders
çoğu (github, NuGet) anahtar/değer deseni içinde çalışır.
Aşağıdaki ayarlar içindeki Microsoft.Configuration.ConfigurationBuilders
tüm anahtar/değer yapılandırma oluşturucuları için geçerlidir.
Yapılandırma oluşturucuları, yapılandırma sisteminin seçili anahtar/değer öğelerini doldurmak için bir dış anahtar/değer bilgisi kaynağı kullanır. Özellikle, <appSettings/>
ve <connectionStrings/>
bölümleri yapılandırma oluşturucularından özel işlem alır. Oluşturucular üç modda çalışır:
Strict
- Varsayılan mod. Bu modda yapılandırma oluşturucusu yalnızca iyi bilinen anahtar/değer odaklı yapılandırma bölümlerinde çalışır. Strict
modu, bölümdeki her anahtarı numaralandırır. Dış kaynakta eşleşen bir anahtar bulunursa:
Greedy
- Bu mod modla Strict
yakından ilgilidir. Özgün yapılandırmada zaten var olan anahtarlar ile sınırlı olmak yerine:
Expand
- Bir yapılandırma bölümü nesnesine ayrıştırmadan önce ham XML üzerinde çalışır. Bir dizedeki belirteçlerin genişletilmesi olarak düşünülebilir. Ham XML dizesinin desenle ${token}
eşleşen herhangi bir bölümü belirteç genişletme için bir adaydır. Dış kaynakta karşılık gelen değer bulunmazsa belirteç değiştirilmez. Bu modda oluşturucular ve <connectionStrings/>
bölümleriyle <appSettings/>
sınırlı değildir.
Web.config dosyasından aşağıdaki işaretleme, EnvironmentConfigBuilder'ı modda Strict
etkinleştirir:
<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="MyEnvironment"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
</builders>
</configBuilders>
<appSettings configBuilders="MyEnvironment">
<add key="ServiceID" value="ServiceID value from web.config" />
<add key="ServiceKey" value="ServiceKey value from web.config" />
</appSettings>
<connectionStrings configBuilders="MyEnvironment">
<add name="default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
Aşağıdaki kod, önceki web.config dosyasında gösterilen ve <connectionStrings/>
dosyasını okur<appSettings/>
:
using System;
using System.Configuration;
using System.Web.UI;
namespace MyConfigBuilders
{
public partial class About : Page
{
public string ServiceID { get; set; }
public string ServiceKey { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["ServiceID"];
ServiceKey = ConfigurationManager.AppSettings["ServiceKey"];
ConString = ConfigurationManager.ConnectionStrings["default"]
?.ConnectionString;
}
}
}
Yukarıdaki kod, özellik değerlerini şu şekilde ayarlar:
Örneğin, ServiceID
şunları içerir:
ServiceID
ayarlanmadıysa "web.config dosyasından ServiceID değeri".ServiceID
değeri.Aşağıdaki görüntüde, ortam düzenleyicisinde <appSettings/>
önceki web.config dosyasındaki anahtarlar/değerler gösterilmektedir:
Not: Ortam değişkenlerindeki değişiklikleri görmek için Visual Studio'dan çıkıp yeniden başlatmanız gerekebilir.
Anahtar ön ekleri, anahtarların ayarlanmasını basitleştirebilir çünkü:
Ortam değişkenleri aracılığıyla yapılandırmaya hem hem de <appSettings/>
<connectionStrings/>
eklemek için aşağıdaki yaklaşımlardan herhangi birini kullanın:
EnvironmentConfigBuilder
varsayılan Strict
modda ve yapılandırma dosyasında uygun anahtar adlarıyla. Yukarıdaki kod ve işaretleme bu yaklaşımı benimser. Bu yaklaşımı kullanarak hem hem de içinde aynı adlandırılmış anahtarlara sahip olmanıza gerek yoktur.<appSettings/>
<connectionStrings/>
stripPrefix
ile iki EnvironmentConfigBuilder
s Greedy
modu kullanın. Bu yaklaşımla, uygulama yapılandırma dosyasını güncelleştirmeye gerek kalmadan okuyabilir <appSettings/>
ve <connectionStrings/>
okuyabilir. Bir sonraki bölüm olan stripPrefix, bunun nasıl yapılacağını gösterir.EnvironmentConfigBuilder
s Greedy
kullanın. Bu yaklaşımda, anahtar adlarının ön eke göre farklı olması gerektiğinden yinelenen anahtar adlara sahip olamazsınız. Örneğin:<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
<add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
</builders>
</configBuilders>
<appSettings configBuilders="AS_Environment">
<add key="AppSetting_ServiceID" value="ServiceID value from web.config" />
<add key="AppSetting_default" value="AppSetting_default value from web.config" />
</appSettings>
<connectionStrings configBuilders="CS_Environment">
<add name="ConnStr_default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
Yukarıdaki işaretlemeyle, iki farklı bölümün yapılandırmasını doldurmak için aynı düz anahtar/değer kaynağı kullanılabilir.
Aşağıdaki görüntüde, ortam düzenleyicisinde <appSettings/>
önceki web.config dosyasındaki ve <connectionStrings/>
anahtarları/değerleri gösterilmektedir:
Aşağıdaki kod, önceki web.config dosyasında bulunan ve <connectionStrings/>
anahtarlarını/değerlerini okur<appSettings/>
:
public partial class Contact : Page
{
public string ServiceID { get; set; }
public string AppSetting_default { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["AppSetting_ServiceID"];
AppSetting_default = ConfigurationManager.AppSettings["AppSetting_default"];
ConString = ConfigurationManager.ConnectionStrings["ConnStr_default"]
?.ConnectionString;
}
}
Yukarıdaki kod, özellik değerlerini şu şekilde ayarlar:
Örneğin, önceki web.config dosyası, önceki ortam düzenleyicisi görüntüsündeki anahtarlar/değerler ve önceki kod kullanılarak aşağıdaki değerler ayarlanır:
Anahtar | Değer |
---|---|
AppSetting_ServiceID | Env değişkenlerinden AppSetting_ServiceID |
AppSetting_default | env'den değer AppSetting_default |
ConnStr_default | env'den ConnStr_default değer |
stripPrefix
: boolean, varsayılan olarak false
olarak gösterilir.
Yukarıdaki XML işaretlemesi, uygulama ayarlarını bağlantı dizesi'lerden ayırır, ancak web.config dosyasındaki tüm anahtarların belirtilen ön eki kullanmasını gerektirir. Örneğin, önek AppSetting
anahtara ServiceID
("AppSetting_ServiceID") eklenmelidir. ilestripPrefix
, ön ek web.config dosyasında kullanılmaz. Ön ek, yapılandırma oluşturucu kaynağında (örneğin, ortamda) gereklidir. Geliştiricilerin çoğunun kullanacağını stripPrefix
tahmin ediyoruz.
Uygulamalar genellikle ön ekten çıkar. Aşağıdaki web.config ön ekini sorr:
<configuration>
<configSections>
<section name="configBuilders"
type="System.Configuration.ConfigurationBuildersSection,
System.Configuration, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
restartOnExternalChanges="false" requirePermission="false" />
</configSections>
<configBuilders>
<builders>
<add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
stripPrefix="true"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
<add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
stripPrefix="true"
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment,
Version=1.0.0.0, Culture=neutral" />
</builders>
</configBuilders>
<appSettings configBuilders="AS_Environment">
<add key="ServiceID" value="ServiceID value from web.config" />
<add key="default" value="AppSetting_default value from web.config" />
</appSettings>
<connectionStrings configBuilders="CS_Environment">
<add name="default" connectionString="Data Source=web.config/mydb.db" />
</connectionStrings>
Yukarıdaki web.config dosyasında default
anahtar hem hem <connectionStrings/>
de <appSettings/>
içindedir.
Aşağıdaki görüntüde, ortam düzenleyicisinde <appSettings/>
önceki web.config dosyasındaki ve <connectionStrings/>
anahtarları/değerleri gösterilmektedir:
Aşağıdaki kod, önceki web.config dosyasında bulunan ve <connectionStrings/>
anahtarlarını/değerlerini okur<appSettings/>
:
public partial class About2 : Page
{
public string ServiceID { get; set; }
public string AppSetting_default { get; set; }
public string ConString { get; set; }
protected void Page_Load(object sender, EventArgs e)
{
ServiceID = ConfigurationManager.AppSettings["ServiceID"];
AppSetting_default = ConfigurationManager.AppSettings["default"];
ConString = ConfigurationManager.ConnectionStrings["default"]
?.ConnectionString;
}
}
Yukarıdaki kod, özellik değerlerini şu şekilde ayarlar:
Örneğin, önceki web.config dosyası, önceki ortam düzenleyicisi görüntüsündeki anahtarlar/değerler ve önceki kod kullanılarak aşağıdaki değerler ayarlanır:
Anahtar | Değer |
---|---|
ServiceID | Env değişkenlerinden AppSetting_ServiceID |
varsayılan | env'den değer AppSetting_default |
varsayılan | env'den ConnStr_default değer |
tokenPattern
: Dize, varsayılan olarak @"\$\{(\w+)\}"
Expand
Oluşturucuların davranışı ham XML'de gibi ${token}
görünen belirteçler arar. Arama varsayılan normal ifadesiyle @"\$\{(\w+)\}"
yapılır. Eşleşen \w
karakter kümesi XML'den daha katıdır ve birçok yapılandırma kaynağı izin verir. Belirteç adında gerekenden daha fazla @"\$\{(\w+)\}"
karakter olduğunda kullanıntokenPattern
.
tokenPattern
:Dizgi:
<add name="Environment"
[mode|prefix|stripPrefix|tokenPattern]
type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Environment" />
name
Öznitelik değeri rastgeledir.Not: Windows kapsayıcı ortamında, çalışma zamanında ayarlanan değişkenler yalnızca EntryPoint işlem ortamına eklenir. Hizmet olarak veya EntryPoint olmayan bir işlem olarak çalışan uygulamalar, kapsayıcıdaki bir mekanizma aracılığıyla başka bir şekilde eklenmediği sürece bu değişkenleri almaz. IIS/ASP.NET tabanlı kapsayıcılar için, ServiceMonitor.exe'nin geçerli sürümü bunu yalnızca DefaultAppPool'da işler. Diğer Windows tabanlı kapsayıcı değişkenlerinin EntryPoint dışı işlemler için kendi ekleme mekanizmalarını geliştirmesi gerekebilir.
Uyarı
Parolaları, hassas bağlantı dizesi veya diğer hassas verileri asla kaynak kodunda depolamayın. Üretim gizli dizileri geliştirme veya test için kullanılmamalıdır.
<add name="UserSecrets"
[mode|prefix|stripPrefix|tokenPattern]
(userSecretsId="{secret string, typically a GUID}" | userSecretsFile="~\secrets.file")
[optional="true"]
type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />
Yukarıdaki XML'de yol userSecretsFile
veya ~\
kullanabilir~/
. Örneğin, yol olarak userSecretsFile="~/secrets.file
yazılabilir. Daha fazla bilgi için ConfigurationBuilders Yardımcı Programları sınıfına bakın.
Bu yapılandırma oluşturucusu, ASP.NET Core Secret Manager'a benzer bir özellik sağlar.
UserSecretsConfigBuilder .NET Framework projelerinde kullanılabilir, ancak gizli dizi dosyası belirtilmelidir. Alternatif olarak, proje dosyasında özelliğini tanımlayabilir UserSecretsId
ve ham gizli dizi dosyasını okumak için doğru konumda oluşturabilirsiniz. Dış bağımlılıkları projenizin dışında tutmak için gizli dosya XML biçimindedir. XML biçimlendirmesi bir uygulama ayrıntısıdır ve biçime bağlı olmamalıdır. .NET Core projeleriyle bir secrets.json dosyası paylaşmanız gerekiyorsa SimpleJsonConfigBuilder'ı kullanmayı göz önünde bulundurun. SimpleJsonConfigBuilder
.NET Core biçimi de değiştirilebilir bir uygulama ayrıntısı olarak kabul edilmelidir.
için UserSecretsConfigBuilder
yapılandırma öznitelikleri:
userSecretsId
- Bu, xml gizli dizileri dosyasını tanımlamak için tercih edilen yöntemdir. Bu tanımlayıcıyı depolamak için bir UserSecretsId
proje özelliği kullanan .NET Core'a benzer şekilde çalışır. Dize benzersiz olmalıdır, GUID olması gerekmez. Bu öznitelikle, bu tanımlayıcıya UserSecretsConfigBuilder
ait gizli dizi dosyası için iyi bilinen bir yerel konumda (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml
) görünüm.userSecretsFile
- Gizli dizileri içeren dosyayı belirten isteğe bağlı bir öznitelik. Karakter ~
başlangıçta uygulama köküne başvurmak için kullanılabilir. Bu öznitelik veya userSecretsId
öznitelik gereklidir. Her ikisi de belirtilirse öncelik userSecretsFile
kazanır.optional
: boolean, varsayılan değer true
- Gizli dizi dosyası bulunamazsa özel durumu engeller.name
Öznitelik değeri rastgeledir.Gizli dizi dosyası aşağıdaki biçime sahiptir:
<?xml version="1.0" encoding="utf-8" ?>
<root>
<secrets ver="1.0">
<secret name="secret key name" value="secret value" />
</secrets>
</root>
<add name="AzureKeyVault"
[mode|prefix|stripPrefix|tokenPattern]
(vaultName="MyVaultName" |
uri="https:/MyVaultName.vault.azure.net")
[version="secrets version"]
[preloadSecretNames="true"]
type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Azure" />
AzureKeyVaultConfigBuilder, Azure Key Vault'ta depolanan değerleri okur.
vaultName
gereklidir (kasanın adı veya kasanın URI'si). Diğer öznitelikler, hangi kasaya bağlanacakları konusunda denetime izin verir, ancak yalnızca uygulama ile Microsoft.Azure.Services.AppAuthentication
çalışan bir ortamda çalışmıyorsa gereklidir. Azure Hizmetleri Kimlik Doğrulama kitaplığı, mümkünse yürütme ortamından bağlantı bilgilerini otomatik olarak almak için kullanılır. Bir bağlantı dizesi sağlayarak bağlantı bilgilerinin otomatik olarak alınabilmesini geçersiz kılabilirsiniz.
vaultName
- Sağlanmadıysa uri
gereklidir. Azure aboneliğinizde anahtar/değer çiftlerinin okunduğu kasanın adını belirtir.uri
- Belirtilen uri
değere sahip diğer Key Vault sağlayıcılarına bağlanır. Belirtilmezse Azure (vaultName
) kasa sağlayıcısıdır.version
- Azure Key Vault, gizli diziler için bir sürüm oluşturma özelliği sağlar. Belirtilirse version
, oluşturucu yalnızca bu sürümle eşleşen gizli dizileri alır.preloadSecretNames
- Varsayılan olarak, bu oluşturucu başlatıldığında anahtar kasasındaki tüm anahtar adlarını sorgular. Tüm anahtar değerlerinin okunmasını önlemek için bu özniteliği olarak false
ayarlayın. Bunu, gizli dizileri birer birer okuyacak şekilde false
ayarlamak. Kasa "Get" erişimine izin veriyor ancak "Liste" erişimine izin vermiyorsa, gizli dizileri birer birer okumak yararlı olabilir. Not: Modu kullanırken Greedy
, preloadSecretNames
(varsayılan) olmalıdır true
.<add name="KeyPerFile"
[mode|prefix|stripPrefix|tokenPattern]
(directoryPath="PathToSourceDirectory")
[ignorePrefix="ignore."]
[keyDelimiter=":"]
[optional="false"]
type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />
KeyPerFileConfigBuilder , bir dizinin dosyalarını değer kaynağı olarak kullanan temel bir yapılandırma oluşturucudur. Dosyanın adı anahtar, içerik ise değerdir. Bu yapılandırma oluşturucusu, düzenlenmiş bir kapsayıcı ortamında çalışırken yararlı olabilir. Docker Swarm ve Kubernetes gibi sistemler, windows kapsayıcılarını bu dosya başına anahtar biçiminde düzenler secrets
.
Öznitelik ayrıntıları:
directoryPath
-Gerekli. Değerler için aranacak yolu belirtir. Windows gizli dizileri için Docker varsayılan olarak C:\ProgramData\Docker\secrets dizininde depolanır.ignorePrefix
- Bu ön ek ile başlayan dosyalar dışlanır. Varsayılan olarak "yoksay".keyDelimiter
- Varsayılan değer: null
. Belirtilirse, yapılandırma oluşturucusu dizinin birden çok düzeyinden geçirerek bu sınırlayıcıyla anahtar adları oluşturur. Bu değer ise null
, yapılandırma oluşturucusu yalnızca dizinin en üst düzeyine bakar.optional
- Varsayılan değer: false
. Kaynak dizin yoksa yapılandırma oluşturucusunun hatalara neden olup olmayacağını belirtir.Uyarı
Parolaları, hassas bağlantı dizesi veya diğer hassas verileri asla kaynak kodunda depolamayın. Üretim gizli dizileri geliştirme veya test için kullanılmamalıdır.
<add name="SimpleJson"
[mode|prefix|stripPrefix|tokenPattern]
jsonFile="~\config.json"
[optional="true"]
[jsonMode="(Flat|Sectional)"]
type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
Microsoft.Configuration.ConfigurationBuilders.Json" />
.NET Core projeleri, yapılandırma için sık sık JSON dosyaları kullanır. SimpleJsonConfigBuilder oluşturucusu .NET Framework'te .NET Core JSON dosyalarının kullanılmasına izin verir. Bu yapılandırma oluşturucusu düz anahtar/değer kaynağından .NET Framework yapılandırmasının belirli anahtar/değer alanlarına temel bir eşleme sağlar. Bu yapılandırma oluşturucu hiyerarşik yapılandırmalar sağlamaz. JSON yedekleme dosyası, karmaşık bir hiyerarşik nesneye değil, sözlüğe benzer. Çok düzeyli bir hiyerarşik dosya kullanılabilir. Bu sağlayıcı flatten
, sınırlayıcı olarak kullanarak :
her düzeye özellik adını ekleyerek derinliği gösterir.
Öznitelik ayrıntıları:
jsonFile
-Gerekli. Okunacak JSON dosyasını belirtir. Karakter ~
başlangıçta uygulama köküne başvurmak için kullanılabilir.
optional
- Boole değeri, varsayılan değerdir true
. JSON dosyası bulunamazsa özel durum oluşturma işlemini engeller.
jsonMode
- [Flat|Sectional]
. Flat
varsayılan değerdir. olduğunda jsonMode
Flat
, JSON dosyası tek bir düz anahtar/değer kaynağıdır. EnvironmentConfigBuilder
ve AzureKeyVaultConfigBuilder
aynı zamanda tek düz anahtar/değer kaynaklarıdır. SimpleJsonConfigBuilder
modunda yapılandırıldığındaSectional
:
{
"appSettings" : {
"setting1" : "value1",
"setting2" : "value2",
"complex" : {
"setting1" : "complex:value1",
"setting2" : "complex:value2",
}
}
}
Aspnet/MicrosoftConfigurationBuilders GitHub deposunda ConfigurationBuilders Yürütme Sırası'na bakın.
Yapılandırma oluşturucuları gereksinimlerinizi karşılamıyorsa özel bir tane yazabilirsiniz. KeyValueConfigBuilder
Temel sınıf, değiştirme modlarını ve ön ek sorunlarının çoğunu işler. Uygulayan bir projenin yalnızca:
GetAllValues
aracılığıyla GetValue
temel bir anahtar/değer çifti kaynağı uygulayın:using Microsoft.Configuration.ConfigurationBuilders;
using System.Collections.Generic;
public class MyCustomConfigBuilder : KeyValueConfigBuilder
{
public override string GetValue(string key)
{
// Key lookup should be case-insensitive, because most key/value collections in
// .NET Framework config sections are case-insensitive.
return "Value for given key, or null.";
}
public override ICollection<KeyValuePair<string, string>> GetAllValues(string prefix)
{
// Populate the return collection.
return new Dictionary<string, string>() { { "one", "1" }, { "two", "2" } };
}
}
KeyValueConfigBuilder
Temel sınıf, anahtar/değer yapılandırma oluşturucuları arasında iş ve tutarlı davranışın çoğunu sağlar.
Ekinlikler
31 Mar 23 - 2 Nis 23
Microsoft Fabric, Power BI, SQL ve yapay zeka topluluğu tarafından yönetilen nihai etkinlik. 31 Mart - 2 Nisan 2025.
Bugün kaydolunEğitim