daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5262 from aspnet/master 

Update live with current master
pull/5342/head
Rick Anderson 2018-01-24 14:27:08 -10:00 committed by GitHub
parent 060879fcf3 b37804bf81
commit 83b5a4715f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 42 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
aspnetcore/fundamentals/configuration/index.md
View File

@ -15,7 +15,7 @@ uid: fundamentals/configuration/index
By [Rick Anderson](https://twitter.com/RickAndMSFT), [Mark Michaelis](http://intellitect.com/author/mark-michaelis/), [Steve Smith](https://ardalis.com/), [Daniel Roth](https://github.com/danroth27), and [Luke Latham](https://github.com/guardrex)
The Configuration API provides a way to configure an ASP.NET Core web app based on a list of name-value pairs. Configuration is read at runtime from multiple sources. You can group these name-value pairs into a multi-level hierarchy.
The Configuration API provides a way to configure an ASP.NET Core web app based on a list of name-value pairs. Configuration is read at runtime from multiple sources. Name-value pairs can be grouped into a multi-level hierarchy.
There are configuration providers for:
@ -54,7 +54,7 @@ Console.Write($"{Configuration["wizards:0:Name"]}");
// Output: Gandalf
```
Name-value pairs written to the built-in [Configuration](/dotnet/api/microsoft.extensions.configuration) providers are **not** persisted. However, you can create a custom provider that saves values. See [custom configuration provider](xref:fundamentals/configuration/index#custom-config-providers).
Name-value pairs written to the built-in [Configuration](/dotnet/api/microsoft.extensions.configuration) providers are **not** persisted. However, a custom provider that saves values can be created. See [custom configuration provider](xref:fundamentals/configuration/index#custom-config-providers).
The preceding sample uses the configuration indexer to read values. To access configuration outside of `Startup`, use the *options pattern*. For more information, see the [Options](xref:fundamentals/configuration/options) topic.
@ -88,8 +88,8 @@ Configuration considerations:
* `IOptionsSnapshot` can reload configuration data when it changes. For more information, see [IOptionsSnapshot](xref:fundamentals/configuration/options#reload-configuration-data-with-ioptionssnapshot).,
* Configuration keys are **not** case-sensitive.
* **Never** store passwords or other sensitive data in configuration provider code or in plain text configuration files. Don't use production secrets in your development or test environments. Specify secrets outside of the project so that they can't be accidentally committed to your repository. Learn more about [working with multiple environments](xref:fundamentals/environments) and managing [safe storage of app secrets during development](xref:security/app-secrets).
* If a colon (`:`) can't be used in environment variables on your system, replace the colon (`:`) with a double-underscore (`__`).
* **Never** store passwords or other sensitive data in configuration provider code or in plain text configuration files. Don't use production secrets in development or test environments. Specify secrets outside of the project so that they can't be accidentally committed to a source code repository. Learn more about [working with multiple environments](xref:fundamentals/environments) and managing [safe storage of app secrets during development](xref:security/app-secrets).
* If a colon (`:`) can't be used in environment variables on a system, replace the colon (`:`) with a double-underscore (`__`).
## In-memory provider and binding to a POCO class
@ -97,7 +97,7 @@ The following sample shows how to use the in-memory provider and bind to a class
[!code-csharp[Main](index/sample/InMemory/Program.cs)]
Configuration values are returned as strings, but binding enables the construction of objects. Binding allows you to retrieve POCO objects or even entire object graphs.
Configuration values are returned as strings, but binding enables the construction of objects. Binding allows the retrieval of POCO objects or even entire object graphs.
### GetValue
@ -105,11 +105,11 @@ The following sample demonstrates the [GetValue<T>](/dotnet/api/microsoft.
[!code-csharp[Main](index/sample/InMemoryGetValue/Program.cs?highlight=31)]
The ConfigurationBinder's `GetValue<T>` method allows you to specify a default value (80 in the sample). `GetValue<T>` is for simple scenarios and doesn't bind to entire sections. `GetValue<T>` gets scalar values from `GetSection(key).Value` converted to a specific type.
The ConfigurationBinder's `GetValue<T>` method allows the specification of a default value (80 in the sample). `GetValue<T>` is for simple scenarios and doesn't bind to entire sections. `GetValue<T>` obtains scalar values from `GetSection(key).Value` converted to a specific type.
## Bind to an object graph
You can recursively bind to each object in a class. Consider the following `AppSettings` class:
Each object in a class can be recursively bound. Consider the following `AppSettings` class:
[!code-csharp[Main](index/sample/ObjectGraph/AppSettings.cs)]
@ -180,7 +180,7 @@ Create the custom configuration provider by inheriting from [ConfigurationProvid
The highlighted values from the database ("value_from_ef_1" and "value_from_ef_2") are displayed when the sample is run.
You can add an `EFConfigSource` extension method for adding the configuration source:
An `EFConfigSource` extension method for adding the configuration source can be used:
[!code-csharp[Main](index/sample/CustomConfigurationProvider/EntityFrameworkExtensions.cs?highlight=12)]
@ -326,7 +326,7 @@ If duplicate keys are provided, the last key-value pair is used.
### Switch mappings
When manually building configuration with `ConfigurationBuilder`, you can optionally provide a switch mappings dictionary to the `AddCommandLine` method. Switch mappings allow you to provide key name replacement logic.
When manually building configuration with `ConfigurationBuilder`, a switch mappings dictionary can be added to the `AddCommandLine` method. Switch mappings allow key name replacement logic.
When the switch mappings dictionary is used, the dictionary is checked for a key that matches the key provided by a command-line argument. If the command-line key is found in the dictionary, the dictionary value (the key replacement) is passed back to set the configuration. A switch mapping is required for any command-line key prefixed with a single dash (`-`).
@ -335,7 +335,7 @@ Switch mappings dictionary key rules:
* Switches must start with a dash (`-`) or double-dash (`--`).
* The switch mappings dictionary must not contain duplicate keys.
In the following example, the `GetSwitchMappings` method allows your command-line arguments to use a single dash (`-`) key prefix and avoid leading subkey prefixes.
In the following example, the `GetSwitchMappings` method allows command-line arguments to use a single dash (`-`) key prefix and avoid leading subkey prefixes.
[!code-csharp[Main](index/sample/CommandLine/Program.cs?highlight=10-19,32)]
@ -389,6 +389,10 @@ Left: 1988
A *web.config* file is required when hosting the app in IIS or IIS Express. Settings in *web.config* enable the [ASP.NET Core Module](xref:fundamentals/servers/aspnet-core-module) to launch the app and configure other IIS settings and modules. If the *web.config* file isn't present and the project file includes `<Project Sdk="Microsoft.NET.Sdk.Web">`, publishing the project creates a *web.config* file in the published output (the *publish* folder). For more information, see [Host ASP.NET Core on Windows with IIS](xref:host-and-deploy/iis/index#webconfig).
## Accessing configuration during startup
To access configuration within `ConfigureServices` or `Configure` during startup, see the examples in the [Application startup](xref:fundamentals/startup) topic.
## Additional notes
* Dependency Injection (DI) isn't set up until after `ConfigureServices` is invoked.
@ -396,7 +400,7 @@ A *web.config* file is required when hosting the app in IIS or IIS Express. Sett
* `IConfiguration` has two specializations:
* `IConfigurationRoot` Used for the root node. Can trigger a reload.
* `IConfigurationSection` Represents a section of configuration values. The `GetSection` and `GetChildren` methods return an `IConfigurationSection`.
* Use [IConfigurationRoot](/dotnet/api/microsoft.extensions.configuration.iconfigurationroot) when reloading configuration or need access to each provider. Neither of these situations are common.
* Use [IConfigurationRoot](/dotnet/api/microsoft.extensions.configuration.iconfigurationroot) when reloading configuration or for access to each provider. Neither of these situations are common.
## Additional resources

2
aspnetcore/fundamentals/configuration/index/sample/InMemory/Program.cs
View File

@ -1,7 +1,5 @@
using System;
using System.Collections.Generic;
// Requires NuGet package
// Microsoft.Extensions.Configuration.Json
using Microsoft.Extensions.Configuration;
public class Program

2
aspnetcore/fundamentals/configuration/index/sample/InMemoryGetValue/Program.cs
View File

@ -1,7 +1,5 @@
using System;
using System.Collections.Generic;
// Requires NuGet package
// Microsoft.Extensions.Configuration.Json
using Microsoft.Extensions.Configuration;
public class Program

6
aspnetcore/fundamentals/configuration/options.md
View File

@ -254,6 +254,12 @@ services.PostConfigureAll<MyOptions>("named_options_1", myOptions =>
[IOptionsMonitorCache&lt;TOptions&gt;](/dotnet/api/microsoft.extensions.options.ioptionsmonitorcache-1) (ASP.NET Core 2.0 or later) is used by `IOptionsMonitor` to cache `TOptions` instances. The `IOptionsMonitorCache` invalidates options instances in the monitor so that the value is recomputed ([TryRemove](/dotnet/api/microsoft.extensions.options.ioptionsmonitorcache-1.tryremove)). Values can be manually introduced as well with [TryAdd](/dotnet/api/microsoft.extensions.options.ioptionsmonitorcache-1.tryadd). The [Clear](/dotnet/api/microsoft.extensions.options.ioptionsmonitorcache-1.clear) method is used when all named instances should be recreated on demand.
## Accessing options during startup
`IOptions` can be used in `Configure`, since services are built before the `Configure` method executes. If a service provider is built in `ConfigureServices` to access options, it wouldn't contain any options configurations provided after the service provider is built. Therefore, an inconsistent options state may exist due to the ordering of service registrations.
Since options are typically loaded from configuration, configuration can be used in startup in both `Configure` and `ConfigureServices`. For examples of using configuration during startup, see the [Application startup](xref:fundamentals/startup) topic.
## See also
* [Configuration](xref:fundamentals/configuration/index)

9
aspnetcore/fundamentals/startup.md
View File

@ -32,11 +32,14 @@ Specify the `Startup` class with the [WebHostBuilderExtensions](/dotnet/api/Micr
[!code-csharp[Main](../common/samples/WebApplication1DotNetCore2.0App/Program.cs?name=snippet_Main&highlight=10)]
The `Startup` class constructor accepts dependencies defined by the host. A common use of [dependency injection](xref:fundamentals/dependency-injection) into the `Startup` class is to inject [IHostingEnvironment](/dotnet/api/Microsoft.AspNetCore.Hosting.IHostingEnvironment) to configure services by environment:
The `Startup` class constructor accepts dependencies defined by the host. A common use of [dependency injection](xref:fundamentals/dependency-injection) into the `Startup` class is to inject:
* [IHostingEnvironment](/dotnet/api/Microsoft.AspNetCore.Hosting.IHostingEnvironment) to configure services by environment.
* [IConfiguration](/dotnet/api/microsoft.extensions.configuration.iconfiguration) to configure the app during startup.
[!code-csharp[Main](startup/snapshot_sample/Startup2.cs)]
An alternative to injecting `IHostingStartup` is to use a conventions-based approach. The app can define separate `Startup` classes for different environments (for example, `StartupDevelopment`), and the appropriate startup class is selected at runtime. The class whose name suffix matches the current environment is prioritized. If the app is run in the Development environment and includes both a `Startup` class and a `StartupDevelopment` class, the `StartupDevelopment` class is used. For more information see [Working with multiple environments](xref:fundamentals/environments#startup-conventions).
An alternative to injecting `IHostingEnvironment` is to use a conventions-based approach. The app can define separate `Startup` classes for different environments (for example, `StartupDevelopment`), and the appropriate startup class is selected at runtime. The class whose name suffix matches the current environment is prioritized. If the app is run in the Development environment and includes both a `Startup` class and a `StartupDevelopment` class, the `StartupDevelopment` class is used. For more information, see [Working with multiple environments](xref:fundamentals/environments#startup-conventions).
To learn more about `WebHostBuilder`, see the [Hosting](xref:fundamentals/hosting) topic. For information on handling errors during startup, see [Startup exception handling](xref:fundamentals/error-handling#startup-exception-handling).
@ -78,7 +81,7 @@ For more information on how to use `IApplicationBuilder`, see [Middleware](xref:
[ConfigureServices](/dotnet/api/microsoft.aspnetcore.hosting.iwebhostbuilder.configureservices) and [Configure](/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderextensions.configure) convenience methods can be used instead of specifying a `Startup` class. Multiple calls to `ConfigureServices` append to one another. Multiple calls to `Configure` use the last method call.
[!code-csharp[Main](startup/snapshot_sample/Program.cs?highlight=16,20)]
[!code-csharp[Main](startup/snapshot_sample/Program.cs?highlight=18,22)]
## Startup filters

8
aspnetcore/fundamentals/startup/snapshot_sample/Program.cs
View File

@ -1,6 +1,7 @@
public class Program
{
public static IHostingEnvironment HostingEnvironment { get; set; }
public static IHostingEnvironment HostingEnvironment { get; }
public static IConfiguration Configuration { get; }
public static void Main(string[] args)
{
@ -12,6 +13,7 @@ public class Program
.ConfigureAppConfiguration((hostingContext, config) =>
{
HostingEnvironment = hostingContext.HostingEnvironment;
Configuration = config.Build();
})
.ConfigureServices(services =>
{
@ -28,6 +30,10 @@ public class Program
app.UseExceptionHandler("/Error");
}
// Configuration is available during startup. Examples:
// Configuration["key"]
// Configuration["subsection:suboption1"]
app.UseMvcWithDefaultRoute();
app.UseStaticFiles();
})

8
aspnetcore/fundamentals/startup/snapshot_sample/Startup2.cs
View File

@ -1,11 +1,13 @@
public class Startup
{
public Startup(IHostingEnvironment env)
public Startup(IHostingEnvironment env, IConfiguration config)
{
HostingEnvironment = env;
Configuration = config;
}
public IHostingEnvironment HostingEnvironment { get; }
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
@ -17,5 +19,9 @@ public class Startup
{
// Staging/Production configuration
}
// Configuration is available during startup. Examples:
// Configuration["key"]
// Configuration["subsection:suboption1"]
}
}

2
aspnetcore/includes/mvc-intro/validation.md
View File

@ -77,7 +77,7 @@ Open the *Movie.cs* file and examine the `Movie` class. The `System.ComponentMod
[!code-csharp[Main](../../tutorials/first-mvc-app/start-mvc//sample/MvcMovie/Models/MovieDateRatingDA.cs?highlight=2,6&name=snippet2)]
The `DataType` attributes only provide hints for the view engine to format the data (and supply attributes such as `<a>` for URL's and `<a href="mailto:EmailAddress.com">` for email. You can use the `RegularExpression` attribute to validate the format of the data. The `DataType` attribute is used to specify a data type that's more specific than the database intrinsic type, they're not validation attributes. In this case we only want to keep track of the date, not the time. The `DataType` Enumeration provides for many data types, such as Date, Time, PhoneNumber, Currency, EmailAddress and more. The `DataType` attribute can also enable the application to automatically provide type-specific features. For example, a `mailto:` link can be created for `DataType.EmailAddress`, and a date selector can be provided for `DataType.Date` in browsers that support HTML5. The `DataType` attributes emits HTML 5 `data-` (pronounced data dash) attributes that HTML 5 browsers can understand. The
The `DataType` attributes only provide hints for the view engine to format the data (and supplies elements/attributes such as `<a>` for URL's and `<a href="mailto:EmailAddress.com">` for email. You can use the `RegularExpression` attribute to validate the format of the data. The `DataType` attribute is used to specify a data type that's more specific than the database intrinsic type, they're not validation attributes. In this case we only want to keep track of the date, not the time. The `DataType` Enumeration provides for many data types, such as Date, Time, PhoneNumber, Currency, EmailAddress and more. The `DataType` attribute can also enable the application to automatically provide type-specific features. For example, a `mailto:` link can be created for `DataType.EmailAddress`, and a date selector can be provided for `DataType.Date` in browsers that support HTML5. The `DataType` attributes emits HTML 5 `data-` (pronounced data dash) attributes that HTML 5 browsers can understand. The
`DataType` attributes do **not** provide any validation.
`DataType.Date` doesn't specify the format of the date that's displayed. By default, the data field is displayed according to the default formats based on the server's `CultureInfo`.

4
aspnetcore/tutorials/first-mvc-app-xplat/adding-model.md
View File

@ -56,10 +56,6 @@ Open a terminal window in the project folder and run the following commands:
dotnet restore
dotnet aspnet-codegenerator controller -name MoviesController -m Movie -dc MvcMovieContext --relativeFolderPath Controllers --useDefaultLayout --referenceScriptLibraries
```
> [!NOTE]
> If you get an error when the scaffolding command runs, see [issue 444 in the scaffolding repository](https://github.com/aspnet/scaffolding/issues/444) for a workaround.
The scaffolding engine creates the following:
* A movies controller (*Controllers/MoviesController.cs*)