maxmustermann/dotnet-core
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Create sdk-implicit-refs.md (#432)

Browse source 
* Create sdk-implicit-refs.md

* Create sdk-implicit-items.md

* Update sdk-implicit-items.md
This commit is contained in:
Zlatko Knezevic 2017-01-20 16:02:36 -08:00 committed by GitHub
parent ca015eb654
commit 5280bed407
2 changed files with 56 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
release-notes/sdk-implicit-items.md Normal file
View file

@ -0,0 +1,30 @@
## Implicit compilation sources includes in the Visual Studio 2017 RC3 release of the .NET Core SDK
As part of the RC3 release of Visual Studio 2017, a new version of the .NET Core SDK is included. With that, we've moved the default includes and excludes for compile items and embedded resources to the SDK properties files. This means that you don't need to specify these items in your project file moving forward.
The main reason for doing this is to reduce the clutter on your project file. The defaults that are present in the SDK should cover most common use cases, so there is no need to repeat them in every project that you create. This leads to shorter projects that are much easier to understand as well as edit by hand, if needed.
The table below shows which element and which globs are both included and excluded in the SDK:
| Element | Include glob | Exclude glob | Remove glob |
|-------------------|-------------------------------------------|---------------------------------------------------------------|----------------------------|
| Compile | \*\*/\*.cs (or other language extensions) | \*\*/\*.user; \*\*/\*.\*proj; \*\*/\*.sln; \*\*/\*.vssscc | N/A |
| EmbeddedResource | \*\*/\*.resx | \*\*/\*.user; \*\*/\*.\*proj; \*\*/\*.sln; \*\*/\*.vssscc | N/A |
| None | \*\*/\* | \*\*/\*.user; \*\*/\*.\*proj; \*\*/\*.sln; \*\*/\*.vssscc | - \*\*/\*.cs; \*\*/\*.resx |
If you have globs in your project and you try to build it using the newest SDK, you'll get the following error:
> Duplicate Compile items were included. The .NET SDK includes Compile items from your project directory by default. You can either remove these items from your project file, or set the 'EnableDefaultCompileItems' property to 'false' if you want to explicitly include them in your project file.
In order to get around this error, you can either remove the explicit Compile items that match the ones listed above, or you can set the `<EnableDefaultCompileItems>` property to false, like this:
```xml
<PropertyGroup>
<EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>
```
Setting this property to `false` will override implicit inclusion and the behavior will revert back to the previous SDKs where you had to specify the default globs in your project.
This change does not modify the main mechanics of other includes. However, if you wish to specify, for example, some files to get published with your app, you can still use the known mechanisms in `csproj` for that (for example, the `<Content>` element).
### Recommendation
Moving forward, our recommendation is for you to remove the above default globs from your project and only add globs file paths for those artifacts that your app/library needs for various scenarios (runtime, NuGet packaging, etc.)

26
release-notes/sdk-implicit-refs.md Normal file
View file

@ -0,0 +1,26 @@
## Implicit metapackage package reference in VS2017 RC3 release of the .NET Core SDK
While working with the previous versions of the .NET Core tooling (both project.json and csproj-based tools), you probably have become acquainted with the concept of the "metapackage". It is a dependency/package reference (for example, `Microsoft.NETCore.App` or `NetStandard.Library`) that you add to your project in addition to the target framework (for example, `netcoreapp1.0` or `netstandard1.6`).
During the previous months, we've received a lot of feedback that having two data points in the project file is confusing, especially for the upgrade scenario. For example, if you wanted to upgrade from `netcoreapp1.0` to `netcoreapp1.1`, you had to change the target framework **as well** as change the version of the metapackage. This led many users to errors and weird behaviors.
As part of the RC3 release of the [.NET Core SDK](https://github.com/dotnet/sdk), we've moved to the model where the SDK implies a certain version of the `Microsoft.NETCore.App` and `NetStandard.Library` metapackages based on the framework you're targeting. This change makes targeting easier. The intent is for developers to target .NET Core or .NET Standard using just the targeted framework. The package is, in this context, a pure implementation detail that the developer doesn't have to worry about.
### Behavior description
The metapackage included is tied to the target framework. That means that for `netcoreapp1.0` a proper version of the `Microsoft.NETCore.App` metapackage is referenced. Same goes for `netcoreapp1.1` target framework as well as `netstandard1.x` target frameworks.
As far as the rest of the behavior is concerned, the tools will work as expected and most of the gestures will remain the same (for example, `dotnet restore`).
### Migrating a project
If you have an existing reference to the metapackage in your project.json, the migration (both in `dotnet migrate` as well as Visual Studio 2017) will include that reference in your new csproj project. This will cause the tools to issue the following warning when you try to build your project:
> A PackageReference for [metapackage ID] was included in your project. This package is implicitly referenced by the .NET SDK and you do not typically need to reference it from your project. For more information, see https://aka.ms/sdkimplicitrefs.
This warning simply means that you probably want to remove that package reference from your project file. If you do keep it, the specified version of the metapackage will be used.
## Recommendations
With this new feature, you might be wondering when you should specify a version of the metapackage in the project and when not. Here is the overall guidance:
* For new projects, you should use the template and not add an explicit reference to any metapackage.
* For existing projects, you should remove the reference.
* If you need a specific version of the runtime, you should use the `<RuntimeFrameworkVersion>` property in your project (for example, `1.0.4`) instead of referencing the metapackage.
* This might happen if you are using [self-contained deployments](https://docs.microsoft.com/en-us/dotnet/articles/core/preview3/deploying/#self-contained-deployments-scd) and you need a specific patch version of 1.0.0 LTS runtime, for example.