mono/linux-packaging-mono
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Imported Upstream version 5.0.0.42

Browse Source 
Former-commit-id: fd56571888259555122d8a0f58c68838229cea2b
This commit is contained in:
Xamarin Public Jenkins (auto-signing)
2017-04-10 11:41:01 +00:00
parent 1190d13a04
commit 6bdd276d05
19939 changed files with 3099680 additions and 93811 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
external/corefx/Documentation/project-docs/api-review-process.md vendored Normal file
View File

@@ -0,0 +1,55 @@
# API Review Process
The .NET Framework has a long standing history of taking API usability extremely seriously. Thus, we generally review every single API that is added to the product. This page discusses how we conduct design reviews for components that are open sourced.
## Which APIs should be reviewed?
The rule of thumb is that we (**corefx**) review every API that is being added to the `System.*` namespaces. In some cases, we also review APIs that are added to other namespaces, such as `Microsoft.*`. We mostly do this for high impact APIs, such as Roslyn, and when both the owner of the technology and we feel there is win-win for both sides if we review the APIs. However, we can't scale to review all APIs being added to .NET.
## Process
![API Review Process](../images/api-review-process.png)
## Steps
1. **Requester files an issue**. The issue description should contain a speclet that represents a sketch of the new APIs, including samples on how the APIs are being used. The goal isn't to get a complete API list, but a good handle on how the new APIs would roughly look like and in what scenarios they are being used. Here is [a good example](https://github.com/dotnet/corefx/issues/271).
2. **We assign an owner**. We'll assign a dedicated owner from our side that
sponsors the issue. This is usually the area owner for which the API proposal or design change request was filed for.
3. **Discussion**. The goal of the discussion is to help the assignee to make a
decision whether we want to pursue the proposal or not. In this phase, the goal
isn't necessarily to perform an in-depth review; rather, we want to make sure
that the proposal is actionable, i.e. has a concrete design, a sketch of the
APIs and some code samples that show how it should be used. If changes are necessary, the requester is encouraged to edit the issue description. This allows folks joining later to understand the most recent proposal. To avoid confusion, the requester should maintain a tiny change log, like a bolded "Updates:" followed by a bullet point list of the updates that were being made.
4. **Owner makes decision**. When the owner believes enough information is available to make a decision, she will update the issue accordingly:
* **Mark for review**. If the owner believes the proposal is actionable, she will label the issue with `api-ready-for-review`.
* **Close as not actionable**. In case the issue didn't get enough traction to be distilled into a concrete proposal, she will close the issue.
* **Close as won't fix as proposed**. Sometimes, the issue that is raised is a good one but the owner thinks the concrete proposal is not the right way to tackle the problem. In most cases, the owner will try to steer the discussion in a direction that results in a design that we believe is appropriate. However, for some proposals the problem is at the heart of the design which can't easily be changed without starting a new proposal. In those cases, the owner will close the issue and explain the issue the design has.
* **Close as won't fix**. Similarly, if proposal is taking the product in a direction we simply don't want to go, the issue might also get closed. In that case, the problem isn't the proposed design but in the issue itself.
5. **API gets reviewed**. The group conducting the review is called *FXDC*, which stands for *framework design core*. In the review, we'll take notes and provide feedback. After the review, we'll publish the notes in the [API Review repository](https://github.com/dotnet/apireviews). A good example is the [review of immutable collections](https://github.com/dotnet/apireviews/tree/master/2015-01-07-immutable). Multiple outcomes are possible:
* **Approved**. In this case the label `api-ready-for-review` is replaced
with `api-approved`.
* **Needs work**. In case we believe the proposal isn't ready yet, we'll
replace the label `api-ready-for-review` with `api-needs-work`.
* **Rejected**. In case we believe the proposal isn't a direction we want to go after, we simply write a comment and close the issue.
## Pull requests
Pull requests against **corefx** shouldn't be submitted before getting approval. Also, we don't want to get work in progress (WIP). The reason being that we want to reduce the number pending PRs so that we can focus on the work the community expects we take action on.
If you want to collaborate with other people on the design, feel free to perform the work in a branch in your own fork. If you want to track your TODOs in the description of a PR, you can always submit a PR against your own fork. Also, feel free to advertise your PR by linking it from from the issue you filed against **corefx** in the first step above.
## API Design Guidelines
The .NET design guidelines are captured in the famous book [Framework Design Guidelines](http://amazon.com/dp/0321545613) by Krzysztof Cwalina and Brad Abrams.
A digest with the most important guidelines are available in our [documentation](../coding-guidelines/framework-design-guidelines-digest.md). Long term, we'd like to publish the individual guidelines in standalone repo on which we can also accept PRs and -- more importantly for API reviews -- link to.
## API Review Notes
The API review notes are being published in [API Review repository](https://github.com/dotnet/apireviews).

20
external/corefx/Documentation/project-docs/branching-guide.md vendored Normal file
View File

@@ -0,0 +1,20 @@
Branching Guide
===============
We will have the following branches in the corefx repository:
* **master**
* Where most development happens
* Submit your PRs here unless you are adding API to a type that exists in the full .NET Framework
* **release/[name]**
* Release branches snapped from master.
* Do not submit pull requests to these branches
* Fixes here do not flow to follow-up releases
* Generally, fixes after a snap needing to make it in to a release will go in to master and get cherry-picked to the release branch.
* **dev/[name]**
* Features (aka topics) under active development by more than one developer.
* Submit PRs here only if you've made prior arrangements to work on something in one of these branches.
* It is up to the developers creating these branches to decide what level of review is required
* These features will only ship if they are successfully pulled to master or future via the standard PR and API review process.

7
external/corefx/Documentation/project-docs/consumes-api.md vendored Normal file
View File

@@ -0,0 +1,7 @@
[Consumes API specification](https://github.com/dotnet/buildtools/blob/master/Documentation/RepoCompose.md#consumes-1)
In CoreFx, we'll be using the RepoUtil tool to generate consumes data. RepoUtil examines all of the repo's project.json
files to determine external dependencies.
We have a lot of differing package dependency versions on libraries in our tree (ie test-runtime, ref assembly packages,
implementation packages, etc...). Our stable versioned dependencies will become fixed package outputs in the consumes API. Prerelease fixed packages will still need to be listed in the "fixedPackages" section of RepoData.json.

30
external/corefx/Documentation/project-docs/contributing.md vendored Normal file
View File

@@ -0,0 +1,30 @@
Contributing to CoreFX
======================
This document describes contribution guidelines that are specific to CoreFX. Please read [.NET Core Guidelines](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing.md) for more general .NET Core contribution guidelines.
Coding Style Changes
--------------------
We intend to bring dotnet/corefx into full conformance with the style guidelines described in [Coding Style](../coding-guidelines/coding-style.md). We plan to do that with tooling, in a holistic way. In the meantime, please:
* **DO NOT** send PRs for style changes. For example, do not send PRs that are focused on changing usage of ```Int32``` to ```int```.
* **DO NOT** send PRs for upgrading code to use newer language features, though it's ok to use newer language features as part of new code that's written. For example, it's ok to use expression-bodied members as part of new code you write, but do not send a PR focused on changing existing properties or methods to use the feature.
* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
API Changes
-----------
* **DO NOT** submit such PRs until the APIs have been approved via the [API Review Process](api-review-process.md).
Pull Requests
-------------
* **DO** submit all code changes via pull requests (PRs) rather than through a direct commit. PRs will be reviewed and potentially merged by the repo maintainers after a peer review that includes at least one maintainer.
* **DO NOT** submit "work in progress" PRs. A PR should only be submitted when it is considered ready for review and subsequent merging by the contributor.
* **DO** give PRs short-but-descriptive names (e.g. "Improve code coverage for System.Console by 10%", not "Fix #1234")
* **DO** refer to any relevant issues, and include [keywords](https://help.github.com/articles/closing-issues-via-commit-messages/) that automatically close issues when the PR is merged.
* **DO** tag any users that should know about and/or review the change.
* **DO** ensure each commit successfully builds. The entire PR must pass all tests in the Continuous Integration (CI) system before it'll be merged.
* **DO** address PR feedback in an additional commit(s) rather than ammending the existing commits, and only rebase/squash them when necessary. This makes it easier for reviewers to track changes. If necessary, squashing should be handled by the merger using the ["squash and merge"](https://github.com/blog/2141-squash-your-commits) feature, and should only be done by the contributor upon request.
* **DO NOT** fix merge conflicts using a merge commit. Prefer `git rebase`.

307
external/corefx/Documentation/project-docs/developer-guide.md vendored Normal file
View File

@@ -0,0 +1,307 @@
Developer Guide
===============
The repo can be built for the following platforms, using the provided setup and the following instructions.
| Chip | Windows | Linux | OS X | FreeBSD |
| :---- | :-----: | :---: | :--: | :--: |
| x64 | ●| ◒| ◒| ◒|
| x86 | ◯| ◯| ◯| ◯|
| ARM32 | ◯| ◯| ◯| ◯|
| | [Instructions](../building/windows-instructions.md) | [Instructions](../building/unix-instructions.md) | [Instructions](../building/unix-instructions.md) | [Instructions](../building/unix-instructions.md) |
Building the repository
=======================
The CoreFX repo can be built from a regular, non-admin command prompt. The build produces multiple binaries that make up the CoreFX libraries and the accompanying tests.
Developer Workflow
------------------
The dev workflow describes the [development process](https://github.com/dotnet/buildtools/blob/master/Documentation/Dev-workflow.md) to follow. It is divided into specific tasks that are fast, transparent and easy to understand.
The tasks are represented in scripts (cmd/sh) in the root of the repo:
* clean - Cleans up the binary output and optionally the working directory (`-all`)
* sync - Pulls down external dependencies needed to build (i.e. build tools, xunit, coreclr, etc)
* build - Builds the shipping libraries in corefx.
* build-tests - Builds and runs the corefx tests.
For more information about the different options that each task has, use the argument `-?` when calling the script. For example:
```
build -?
```
###Build
The CoreFX build has two logical components, the native build which produces the "shims" (which provide a stable interface between the OS and managed code) and
the managed build which produces the MSIL code and nuget packages that make up CoreFX.
Calling the script `build` attempts to build both the native and managed code.
Only use it when the parameters that you are passing to the script apply for both components. Otherwise, use the scripts `build-native` and `build-managed` respectively.
The build configurations are generally defaulted based on where you are building (i.e. which OS or which architecture) but we have a few shortcuts for the individual properties that can be passed to the build scripts:
- `-framework` identifies the target framework for the build. It defaults to `netcoreapp` but possible values include `netcoreapp`, `netfx` or `uap`. (msbuild property `TargetGroup`)
- `-os` identifies the OS for the build. It defaults to the OS you are running on but possible values include `Windows_NT`, `Unix`, `Linux`, or `OSX`. (msbuild property `OSGroup`)
- `-debug|-release` controls the optimization level the compilers use for the build. It defaults to `Debug`. (msbuild property `ConfigurationGroup`)
- `-buildArch` identifies the architecture for the build. It defaults to `x64` but possible values include `x64`, `x86`, `arm`, or `arm64`. (msbuild property `ArchGroup`)
These options are common for build, build-managed, build-native, and build-tests scripts.
For more details on the build configurations see [project-guidelines](../coding-guidelines/project-guidelines.md#build-pivots).
**Note**: Before working on individual projects or test projects you **must** run `build` from the root once before beginning that work. It is also a good idea to run `build` whenever you pull a large set of unknown changes into your branch.
**Common full clean build and test run**
```
clean --all
build
build-tests
```
**Examples**
- Building in debug mode for platform x64
```
build -debug -buildArch=x64
```
- Building for different target frameworks
```
build -framework netcoreapp
build -framework netfx
build -framework uap
```
###Build Native
The native build produces shims over libc, openssl, gssapi, libcurl and libz.
The build system uses CMake (2.8.12 or higher) to generate Makefiles using clang (3.5 or higher).
The build also uses git for generating some version information.
The native component should be buildable on any system.
**Examples**
- Building in debug mode for platform x64
```
build-native -debug -buildArch=x64
```
- The following example shows the argument `--`. Everything that is after it is not going to be processed, and will be passed as-is.
```
build-native -debug -buildArch=arm -- cross verbose
```
For more information about extra parameters take a look at the scripts `build-native` under src/Native.
###Build Managed
Since the managed build uses the .NET Core CLI (which the build will download), managed components can only be built on a subset of distros.
There are some additional prerequisites from the CLI which need to be installed. Both libicu and
libunwind are used by CoreCLR to execute managed code, so they must be
installed. Since CoreFX does not actually link against these packages, runtime
versions are sufficient. We also require curl to be present, which we use to
download the .NET Core CLI.
**Examples**
- Building in debug mode for platform x64
```
build-managed -debug -buildArch=x64
```
- Building in debug mode for platform x64 targeting OS Linux
```
build-managed -debug -buildArch=x64 -os=Linux
```
###Build And Run Tests
To build the tests and run them you can call the build-test script. The same parameters you pass to build should also be passed to build-tests script to ensure you are building and running the tests on the same configuration you have build the product on. However to run tests on the same machine you need to ensure the machine supports the configuration you are building.
**Examples**
- The following shows how to build tests but not run them
```
build-tests -skiptests
```
- The following builds and runs all tests for netcoreapp in release configuration.
```
build-tests -release -framework netcoreapp
```
- The following example shows the argument `--`. Everything that is after it is not going to be processed and it is going to be passed as it is.
Use it to pass extra msbuild properties, in this case to ignore tests ignored in CI.
```
build-tests -- /p:WithoutCategories=IgnoreForCI
```
### Building individual CoreFx DLLs
**Note**: Before working on individual projects or test projects you **must** run `build` from the root once before beginning that work. It is also a good idea to run `build` whenever you pull a large set of unknown changes into your branch.
Under the src directory is a set of directories, each of which represents a particular assembly in CoreFX. See Libary Project Guidelines section under [project-guidelines](../coding-guidelines/project-guidelines.md) for more details about the structure.
For example the src\System.Diagnostics.DiagnosticSource directory holds the source code for the System.Diagnostics.DiagnosticSource.dll assembly.
You can build the DLL for System.Diagnostics.DiagnosticSource.dll by going to the `src\System.Diagnostics.DiagnosticsSource\src` directory and typing `msbuild`. The DLL ends up in `bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource` as well as `bin\runtime\[BuildConfiguration]`.
You can build the tests for System.Diagnostics.DiagnosticSource.dll by going to
`src\System.Diagnostics.DiagnosticSource\tests` and typing `msbuild`.
Some libraries might also have a ref and/or a pkg directory and you can build them in a similar way by typing `msbuild` in that directory.
For libraries that have multiple build configurations the configurations will be listed in the `<BuildConfigurations>` property group, commonly found in a configurations.props file next to the csproj. When building the csproj for a configuration the most compatible one in the list will be choosen and set for the build. For more information about `BuildConfigurations` see [project-guidelines](../coding-guidelines/project-guidelines.md).
**Examples**
- Build project for Linux for netcoreapp
`msbuild System.Net.NetworkInformation.csproj /p:OSGroup=Linux`
- Build project for uap (not if trying to build on non-windows you also need to specify OSGroup=Windows_NT)
`msbuild System.Net.NetworkInformation.csproj /p:TargetGroup=uap`
- Build release version of library
`msbuild System.Net.NetworkInformation.csproj /p:ConfigurationGroup=Release`
**Note:** If building in a non-Windows environment, call `<repo-root>/Tools/msbuild.sh` instead of just `msbuild`.
### Building all for other OSes
By default, building from the root will only build the libraries for the OS you are running on. One can
build for another OS by specifying `build-managed -os=[value]`.
Note that you cannot generally build native components for another OS but you can for managed components so if you need to do that you can do it at the individual project level or build all via build-managed.
### Building in Release or Debug
By default, building from the root or within a project will build the libraries in Debug mode.
One can build in Debug or Release mode from the root by doing `build -release` or `build -debug` or when building a project by specifying `/p:ConfigurationGroup=[Debug|Release]` after the `msbuild` command.
### Building other Architectures
One can build 32- or 64-bit binaries or for any architecture by specifying in the root `build -buildArch=[value]` or in a project `/p:ArchGroup=[value]` after the `msbuild` command.
### Tests
We use the OSS testing framework [xunit](http://xunit.github.io/) with the [BuildTools test targets](https://github.com/dotnet/buildtools/blob/master/Documentation/test-targets-usage.md).
#### Running tests on the command line
By default, the core tests are run as part of `build.cmd` or `build.sh`. If the product binaries are already available, you could do `build-tests` which will build and run the tests.
For more information about cross-platform testing, please take a look [here](https://github.com/dotnet/corefx/blob/master/Documentation/building/cross-platform-testing.md).
If you are interested in building and running the tests only for a specific library, then there are two different ways to do it:
The easiest (and recommended) way to do it, is by simply building the test .csproj file for that library.
```cmd
cd src\System.Collections.Immutable\tests
msbuild /t:BuildAndTest ::or /t:Test to just run the tests if the binaries are already built
msbuild /t:RebuildAndTest ::this will cause a test project to rebuild and then run tests
```
It is possible to pass parameters to the underlying xunit runner via the `XunitOptions` parameter, e.g.:
```cmd
msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests"
```
**Note:** If building in a non-Windows environment, call `./Tools/msbuild.sh` instead of just `msbuild`.
There may be multiple projects in some directories so you may need to specify the path to a specific test project to get it to build and run the tests.
Tests participate in the incremental build. This means that if tests have already been run, and inputs to the incremental build have not changed, rerunning the tests target will not execute the test runner again. To force re-executing tests in this situation, use `/p:ForceRunTests=true`.
#### Running tests in a different target framework
Each test project can potentially have multiple build configurations. There are some tests that might be OS-specific, or might be testing an API that is available only on some target frameworks, so the `BuildConfigurations` property specifies the valid configurations. By default we will build and run only the default build configuration which is `netcoreapp`. The rest of the configurations will need to be built and ran by specifying the configuration options.
```cmd
cd src\System.Runtime\tests
msbuild System.Runtime.Tests.csproj /p:TargetGroup=netfx
```
#### Filtering tests using traits
The tests can also be filtered based on xunit trait attributes defined in [`xunit.netcore.extensions`](https://github.com/dotnet/buildtools/tree/master/src/xunit.netcore.extensions). These attributes are specified above the test method's definition. The available attributes are:
_**`OuterLoop`:**_
Tests marked as `Outerloop` are for scenarios that don't need to run every build. They may take longer than normal tests, cover seldom hit code paths, or require special setup or resources to execute. These tests are excluded by default when testing through msbuild but can be enabled manually by adding the `Outerloop` property e.g.
```cmd
build-managed -Outerloop
```
To run <b>only</b> the Outerloop tests, use the following command:
```cmd
msbuild <csproj_file> /t:BuildAndTest /p:WithCategories=OuterLoop
```
_**`PlatformSpecific(TestPlatforms platforms)`:**_
Use this attribute on test methods to specify that this test may only be run on the specified platforms. This attribute returns the following categories based on platform
- `nonwindowstests` for tests that don't run on Windows
- `nonlinuxtests` for tests that don't run on Linux
- `nonosxtests` for tests that don't run on OS X
When running tests by building a test project, tests that don't apply to the `OSGroup` are not run. For example, to run Linux-specific tests on a Linux box, use the following command line:
```sh
<repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=Linux
```
_**`ActiveIssue(int issue, TestPlatforms platforms)`:**_
Use this attribute over test methods to skip failing tests only on the specific platforms; if no platforms are specified, then the test is skipped on all platforms. This attribute returns the 'failing' category, which is disabled by default.
To run all Linux-compatible tests that are failing:
```sh
<repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=Linux /p:WithCategories=failing
```
_**A few common examples with the above attributes:**_
- Run all tests acceptable on Windows that are not failing:
```cmd
msbuild <csproj_file> /t:BuildAndTest /p:OSGroup=Windows_NT
```
- Run all outer loop tests acceptable on OS X that are currently associated with active issues:
```sh
<repo-root>/Tools/msbuild.sh <csproj_file> /t:BuildAndTest /p:OSGroup=OSX /p:WithCategories="OuterLoop;failing""
```
Alternatively, you can directly invoke the XUnit executable by changing your working directory to the test execution directory at `bin\tests\{OSPlatformConfig)\{Project}.Tests\{TargetGroup}.{TestTFM}\` which is created when the test project is built. For example, the following command runs all Linux-supported inner-loop tests:
```sh
./corerun xunit.console.netcore.exe <test_dll_file> -notrait category=nonlinuxtests -notrait category=OuterLoop
```
### Code Coverage
Code coverage is built into the corefx build system. It utilizes OpenCover for generating coverage data and ReportGenerator for generating reports about that data. To run:
```cmd
:: Run full coverage
build-tests -Coverage
:: To run a single project with code coverage enabled pass the /p:Coverage=true property
cd src\System.Collections.Immutable\tests
msbuild /t:BuildAndTest /p:Coverage=true
```
If coverage succeeds, the code coverage report will be generated automatically and placed in the bin\tests\coverage directory. You can view the full report by opening index.htm
Code coverage reports from the continuous integration system are available from the links on the front page of the corefx repo.
### Building tests with .NET Native (Windows only)
.NET Native is a technology that allows compiling IL applications down into a native executable and minimal set of native DLLs, containing all needed functionality from the .NET Framework in native format. For CoreFX tests, .NET Native support in CoreFX is relatively early, but supported.
```cmd
:: To run a single project with the .NET Native toolchain, set the appropriate build flags:
cd src\Microsoft.CSharp\tests
::TODO: The exact properties needed for .NET Native tests runs after engineering work is TBD
msbuild /t:BuildAndTest /p:TargetGroup=uap /p:UseDotNetNativeToolchain=true
```
If native compilation succeeds, the test will build and run as a native executable named "xunit.console.netcore.exe" in a folder named "native" in the test execution folder. Note many tests in CoreFX are not ready to run though native compilation yet.
A slight variation on these arguments will allow you to build and run against `uap`, the managed version of the UWP Framework subset, used when debugging UWP applications in Visual Studio:
```cmd
:: To run a single project with the .NET Native toolchain, set the appropriate build flags:
cd src\Microsoft.CSharp\tests
msbuild /t:BuildAndTest /p:TargetGroup=uap
```
In this case, your test will get executed within the context of a wrapper UWP application, targeting the Managed uap as opposed to the .NET Native version.
The CoreFX build and test suite is a work in progress, as are the [building and testing instructions](../README.md). The .NET Core team and the community are improving Linux and OS X support on a daily basis and are adding more tests for all platforms. See [CoreFX Issues](https://github.com/dotnet/corefx/issues) to find out about specific work items or report issues.

99
external/corefx/Documentation/project-docs/dogfooding.md vendored Normal file
View File

@@ -0,0 +1,99 @@
# How to patch dotnet CLI with latest CoreFX
This document provides the steps necessary to consume a nightly build of CoreFX
and CoreCLR.
Please note that these steps aren't necessary for official builds -- these steps
are specific to consuming nightlies and thus unsupported builds. Also note that
these steps are likely to change as we're simplifying this experience. Make
sure to consult this document often.
## Install prerequisites
1. Install CLI 2.0.0-alpha SDK
- [Win 64-bit Latest](https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-dev-win-x64.latest.exe)
- [macOS 64-bit Latest](https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-dev-osx-x64.latest.pkg)
- [Others](https://github.com/dotnet/cli/blob/master/README.md)
## Setup the project
1. Create a new project
- Creat a new folder for your app
- Create project file by running `dotnet new`
2. Add the CoreFX MyGet feed to your NuGet configuration.
- You can do this globally but we recommend not doing this as this might
affect other projects on your machine and you probably don't want that.
- Instead, add a `nuget.config` that is local to your project. You can
just put it next to the `.csproj` file.
See the [NuGet docs](https://docs.nuget.org/ndocs/consume-packages/configuring-nuget-behavior)
for details.
```xml
<configuration>
<packageSources>
<add key="CoreFX" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" />
</packageSources>
</configuration>
```
3. Select the nightly build from our feed
- <https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.NETCore.App>
- Presumably you want the latest version.
In order to consume the latest build, you'll need to update your `.csproj`
as follows:
1. Update `TargetFramework`, add `RuntimeIdentifier` as below (ideally
`dotnet.exe` would infer your current architecture but it currently doesn't)
2. Update package reference to match version selected above, as below
```xml
<Project Sdk="Microsoft.NET.Sdk" ToolsVersion="15.0">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp2.0</TargetFramework>
<RuntimeIdentifier>win10-x64</RuntimeIdentifier>
</PropertyGroup>
<!-- Make sure to use Update, not Include! -->
<ItemGroup>
<PackageReference Update="Microsoft.NETCore.App" Version="2.0.0-beta-001386-00" />
</ItemGroup>
</Project>
```
Restore packages so that you're ready to play:
```
$ dotnet restore
```
## Consume the new build
Edit your `Program.cs` to consume the new APIs, for example:
```CSharp
using System;
using System.Net;
class Program
{
static void Main(string[] args)
{
WebUtility.HtmlDecode("&amp;", Console.Out);
Console.WriteLine();
Console.WriteLine("Hello World!");
}
}
```
Run the bits:
```
$ dotnet run
```
Rinse and repeat!

6
external/corefx/Documentation/project-docs/getting-started-core.md vendored Normal file
View File

@@ -0,0 +1,6 @@
Getting Started Writing a .NET Core app and Class Library
=========================================================
For general instructions on how to get started with .NET Core, see the [.NET Core Documentation](https://dotnet.github.io/docs/) site.
There are also instructions available for [targeting .NET Core with MSBuild](target-dotnetcore-with-msbuild.md).

141
external/corefx/Documentation/project-docs/glossary.md vendored Normal file
View File

@@ -0,0 +1,141 @@
# Glossary
Over the years, we've accumulated quite a few terms, platforms, and components that can make it hard for folks (including us) to understand what we're referring to. This document has a list that will help to qualify what we mean by what.
This will also list some aliases. As you'll see the aliases aren't always correct -- they are merely listed to help you find the better and less confusing terminology.
## Terms
In this document, the following terms are used:
* **IL**. Intermediate language. Higher level .NET languages, such as C#, compile down to a hardware agnostic instruction set, which is called Intermediate Language (IL). IL is sometimes referred to as MSIL (Microsoft IL) or CIL (Common IL).
* **GC**. Garbage collector. Garbage collection is an implementation of automatic memory management. .NET Framework and .NET Core currently uses a generational garbage collector, i.e. it groups objects into generations to limit the number of nodes it has to walk for determining which objects are alive. This speeds up collection times.
* **JIT**. Just in time compiler. This technology compiles IL to machine code that the processor understands. It's called JIT because compilation happens on demand and is performed on the same machine the code needs to run on. Since JIT compilation occurs during execution of the application, compile time is part of the run time. Thus, JIT compilers have to trade spending more time optimizing code with the savings the resulting code can produce. But a JIT knows the actual hardware and can free developers from having to ship different implementations. For instance, our vector library relies on the JIT to use the highest available SIMD instruction set.
* **AOT**. Ahead of time compiler. Similar to JIT, this compiler also translates IL to machine code. In contrast to JIT compilation, AOT compilation happens before the application is executed and is usually performed on a different machine. AOT tool chains don't trade runtime for compile time and thus can spend more time optimizing. Since the context of AOT is the entire application, the AOT compiler can also perform cross module linking and whole program analysis, which means that all references are followed and a single executable is produced.
* **NGEN**. Native (image) generation. You can think of this technology as a persistent JIT compiler. It usually compiles code on the machine where the code will be executed, but compilation typically occurs at install time.
* **CLR**. Common language runtime. The exact meaning depends on context, but it usually refers to the runtime of the .NET Framework and includes several components. The CLR is a virtual machine, i.e. it includes the facilities to generate and compile code on-the-fly using a JIT compiler. The existing Microsoft CLR implementation is Windows only.
* **CoreCLR**. Core common language runtime. It's built from the same code base as the CLR. Originally, CoreCLR was the runtime of Silverlight and was designed to run on multiple platforms, specifically Windows and OS X. CoreCLR is now part of .NET Core and represents a simplified version of the CLR. It's still a [cross platform](https://github.com/dotnet/coreclr#build-status) runtime. CoreCLR is also a virtual machine with a JIT.
* **CoreRT**. Core runtime. In contrast to the CLR/CoreCLR, CoreRT is not a virtual machine, i.e. it doesn't include the facilities to generate and run code on-the-fly because it doesn't include a JIT. It does, however, include the GC and the ability for runtime type identification (RTTI) as well as reflection. However, its type system is designed so that metadata for reflection can be omitted. This enables having an AOT tool chain that can link away superfluous metadata and (more importantly) identify code that the application doesn't use.
* **CoreFX**. Core framework. Conceptually a set of `System.*` (and to a limited extent `Microsoft.*`) libraries that make up the lower layer of the .NET library stack. It's what most people would think of as the Base Class Library (BCL). The BCL is a general purpose, lower level set of functionality that higher-level frameworks, such as WCF and ASP.NET, build on. The source code of the .NET Core library stack is contained in the [CoreFX repo](http://github.com/dotnet/corefx). However, the majority of the .NET Core APIs are also available in the .NET Framework, so you can think of CoreFX as a fork of the .NET Framework library stack.
## Platforms
### .NET Framework
**Also referred to as**: Desktop, full framework, in-box framework
This refers to the .NET Framework that first shipped in 2002 and has been updated on a regular basis since then. It's the main framework folks target today and allows you to build a wide variety of applications, such as WinForms, WPF, ASP.NET, and command line tools.
The .NET Framework was designed to run on Windows only. Some versions of the .NET Framework come pre-installed with Windows, some require to be installed. However, in both cases the .NET Framework is a system-wide component. Applications do not include .NET Framework DLLs when deploying; the correct .NET version must be on the machine.
### .NET Core
**Also referred to as**: UWP, ~~Store~~
Originally, .NET Core was the identifier we used to describe the .NET APIs Windows 8 store applications could use. When we designed the API set, we wanted to create a foundation for .NET where portability is a first class concern for the layering and componentization. For more details, read [this blog post](http://blogs.msdn.com/b/dotnet/archive/2014/12/04/introducing-net-core.aspx).
Today, .NET Core is no longer just for store applications. .NET Core is the name for the open source, cross-platform stack that ASP.NET Core and UWP applications are built on. The stack includes a set of framework libraries (CoreFX), a JIT based runtime (CoreCLR), an AOT based runtime (CoreRT), and a set of tooling (such as the dotnet CLI).
That's why referring to .NET Core as 'Store' is no longer correct. But you can think of today's .NET Core as an evolution of the original APIs available for store applications. Many of the original design goals are still relevant, especially around layering and portability.
### Universal Windows Platform (UWP)
**Also referred to as**: Store, WinRT, Metro
The Universal Windows Platform (UWP) is the platform that is used for building modern, touch-enabled Windows applications as well as headless devices for Internet of Things (IoT). It's designed to unify the different types of devices that you may want to target, including PCs, tablets, phablets, phones, and even the Xbox.
UWP provides many services, such as a centralized app store, an execution environment (AppContainer), and a set of Windows APIs to use instead of Win32 (WinRT). UWP has no dependency on .NET; apps can be written in C++, C#, VB.NET, and JavaScript. When using C# and VB.NET the .NET APIs are provided by .NET Core.
### .NET Native
**Also referred to as**: ahead-of-time (AOT), IL compiler (ILC)
.NET Native is a compiler tool chain that will produce native code ahead-of-time (AOT), as opposed to just-in-time (JIT). The compilation can happen on the developer machine as well as on the store side, which allows blending AOT with the benefits of servicing.
You can think of .NET Native as an evolution of NGEN (Native Image Generator): NGEN basically simply runs the JIT up front, the code quality and behavior is identical to the JITed version. Another downside of NGEN is that it happens on the user's machine, rather than the developer's machine. NGEN is also at the module level, i.e. for each MSIL assembly there is a corresponding NGEN'ed assembly that contains the native code. .NET Native on the other hand is a C++ like compiler and linker. It will remove unused code, spend more time optimizing it, and produce a single, merged module that represents the closure of the application.
UWP was the first application model that was supported by .NET Native. We now also support building native console applications for Windows, OS X and Linux.
### Rotor
**Also referred to as**: Shared Source Common Language Infrastructure (SSCLI)
Pretty much at the same time the .NET Framework was released, Microsoft also published Rotor, which is the source code for an implementation of ECMA 335 (Common Language Infrastructure), which is the specification behind .NET.
While parts of the source were identical with the .NET Framework, many pieces had prototypic implementations instead: the purpose of Rotor wasn't to provide a production ready .NET implementation but to provide a platform for research, academia, and validation that the ECMA 335 specification itself can be implemented.
It's also worth pointing out that the source code of Rotor was not released under an open source license (i.e. not approved by OSI) and has not been officially updated since .NET Framework 2.0.
### Mono
Mono is an open source alternative to the .NET Framework. Mono started around the same time the .NET Framework was first released. Since Microsoft didn't release Rotor as open source, Mono was forced to start from scratch and is thus a complete re-implementation of the .NET Framework with no shared code.
When .NET Core was released under the MIT license, Microsoft also released large chunks of the .NET Framework under the MIT license as well, which can be found [here](https://github.com/microsoft/referencesource). This enabled the Mono community to use the same code the .NET Framework uses in order to close gaps and avoid behavioral differences.
Mono is primarily used to run .NET applications on Linux and Mac OS X (though to get into the Mac App Store you need Xamarin, see below). There are ports of Mono to other platforms, see [Mono's Supported Platforms](http://www.mono-project.com/docs/about-mono/supported-platforms/)
Mono has implementations (though not necessarily complete) of WinForms, ASP.NET, and System.Drawing.
### Xamarin
Xamarin is a commercial offering for building mobile applications targeting Android, iOS and Mac OS X Store. It's based on Mono, and on iOS and Android surfaces a different API profile, called the mobile profile. The subsetting was necessary to reduce the footprint, both by shipping smaller versions of the system libraries as well as making them more linker friendly. While Mono runs on Mac OS X without Xamarin, their linker is required make the app package for the Mac App Store. Xamarin ships a full static compiler on iOS, as the platform does not support dynamic code generation.
## Frameworks
### Language-Integrated Query
**Also referred to as**: LINQ
Introduced in .NET Framework 3.5, Language-Integrated Query's (LINQ) goal to make data processing easier. LINQ is primarily a collection of methods that extend `IEnumerable` and `IEnumerable<T>`. LINQ is intended to be used with extension methods and Lambda functions (added in C# 3.0 and VB 9.0 at the same time as .NET Framework 3.5 was released) allowing for a function style of programing.
A simple example of LINQ is
```csharp
var odds = source.Where(obj => obj.Id == 1).ToArray();
```
####IQueryable&lt;T&gt; and Expressions
One of the big advantages of using LINQ over more common data processing patterns is that the function given to the LINQ function can be converted to an expression and then executed in some other form, like SQL or on another machine across the network. An expression is a in-memory representation of some logic to follow.
For example, in the above sample `source` could actually be a database connection and the function call `Where(obj => obj.Id == 1)` would be conveted to a SQL WHERE clause: `WHERE ID = 1`, and then executed on the SQL server.
####Parallel LINQ
**Also referred to as**: PLINQ
Also introduced in .NET Framework 3.5 Parallel LINQ. Parallel LINQ has a subset of the methods the LINQ does but may execute the iterations on different threads in any order. Generally to use Parallel LINQ you would just call the `AsParallel()` method on a collection implementing `IEnumerable`. And if at any point you wanted to return to "normal LINQ you can just call `AsSequential()`.
### JSON.NET
Released in June 2006 by [James Newton-King](https://twitter.com/JamesNK), JSON.NET has become the defacto standard for JSON serialization and deserialization in .NET. It is [open source](https://github.com/JamesNK/Newtonsoft.Json) and support almost every platform .NET code can run on (.NET Framework 2.0, 3.0, 3.5, 4.0, and 4.5; Mono; MonoTouch/Xamarin.iOS; MonoDroid/Xamarin.Android; Silverlight 3, 4, and 5; Windows Phone 8, 8, and 8.1; Windows 8 Store; .NET Core).
### Windows Forms
**Also referred to as**: WinForms
Windows Forms is an API provided by the .NET Framework (mostly in the `System.Windows.Forms` namespace) for creating desktop applications. Windows Forms provides an event-driven model for application development on top of the native loop-driven Win32 model. Mono [has an implementation](http://www.mono-project.com/docs/gui/winforms/) of Windows Forms, though it is not complete, since some parts of Windows Forms are tied to the Windows platform.
Windows Forms is in maintenance mode now. That means new features will generally not be added.
### Windows Presentation Foundation
**Also referred to as**: WPF, Avalon
Introduced in .NET Framework 3.0, Windows Presentation Foundation (WPF) was a new API for creating desktop applications. Like Windows Forms, WPF is event-driven. However, instead of using GDI/GDI+ for drawing applications, WPF used DirectX. Using DirectX allowed WPF applications to use the GPU for rendering, freeing the CPU for other tasks. WPF also introduced XAML, an XML-based language which allows a declarative way to describe user interfaces and data binding to models (XAML is used by Silverlight, UWP, and Xamarin as well).
The .NET platform currently doesn't contain a cross-platform XAML-based UI stack. There are, however, various community projects in that space:
* [CSHTML5](http://www.cshtml5.com/): A product to compile WPF/.NET Framework applications into HTML5/CSS3/ECMAScript5 applications.
* [WPFLight](https://github.com/ronnycsharp/WPFLight): An OSS project to create WPF on top of XNA/MonoGame.
* [Perspex](https://github.com/Perspex/Perspex): A cross-platform UI framework based on WPF.
* [Granular](https://github.com/yuvaltz/Granular): A OSS project to allow WPF applications to run in the browser.

109
external/corefx/Documentation/project-docs/issue-guide.md vendored Normal file
View File

@@ -0,0 +1,109 @@
Issue Guide
===========
This page outlines how the CoreFx team thinks about and handles issues. For us, issues on GitHub represent actionable work that should be done at some future point. It may be as simple as a small product or test bug or as large as the work tracking the design of a new feature. However, it should be work that falls under the charter of CoreFx, which is a collection of foundational libraries that make up the .NET Core development stack. We will keep issues open even if the CoreFx team internally has no plans to address them in an upcoming release, as long as we consider the issue to fall under our purview.
### When we close issues
As noted above, we don't close issues just because we don't plan to address them in an upcoming release. So why do we close issues? There are few major reasons:
1. Issues unrelated to CoreFx. When possible, we'll try to find a better home for the issue and point you to it.
2. Cross cutting work better suited for another team. Sometimes the line between the framework, languages and runtime blurs. For some issues, we may feel that the work is better suited for the runtime team, language team or other partner. In these cases, we'll close the issue and open it with the partner team. If they end up not deciding to take on the issue, we can reconsider it here.
3. Nebulous and Large open issues. Large open issues are sometimes better suited for [User Voice](http://visualstudio.uservoice.com/forums/121579-visual-studio/category/31481--net), especially when the work will cross the boundaries of the framework, language and runtime. A good example of this is the SIMD support we recently added to CoreFx. This started as a [User Voice request](https://visualstudio.uservoice.com/forums/121579-visual-studio-2015/suggestions/2212443-c-and-simd), and eventually turned into work for both the core libraries and runtime.
Sometimes after debate, we'll decide an issue isn't a good fit for CoreFx. In that case, we'll also close it. Because of this, we ask that you don't start working on an issue until it's tagged with [up for grabs](https://github.com/dotnet/corefx/labels/up%20for%20grabs) or [api-approved](https://github.com/dotnet/corefx/labels/api-approved). Both you and the team will be unhappy if you spend time and effort working on a change we'll ultimately be unable to take. We try to avoid that.
### Labels
We use GitHub [labels](https://github.com/dotnet/corefx/labels) on our issues in order to classify them. We have the following categories per issue:
* **Area**: These area-&#42; labels (e.g. [area-System.Collections](https://github.com/dotnet/corefx/labels/area-System.Collections)) call out the assembly or assemblies the issue applies to. In addition to labels per assembly, we have a few other area labels: [area-Infrastructure](https://github.com/dotnet/corefx/labels/area-Infrastructure), for issues that relate to our build or test infrastructure, and [area-Meta](https://github.com/dotnet/corefx/labels/area-Meta) for issues that deal with the repository itself, the direction of the .NET Core Platform, our processes, etc. See [full list of areas](#areas).
* **Issue Type**: These labels classify the type of issue. We use the following types:
* [bug](https://github.com/dotnet/corefx/labels/bug): Bugs in an assembly.
* api-&#42; ([api-approved](https://github.com/dotnet/corefx/labels/api-approved), [api-needs-work](https://github.com/dotnet/corefx/labels/api-needs-work)): Issues which would add APIs to an assembly (see [API Review process](api-review-process.md) for details).
* [enhancement](https://github.com/dotnet/corefx/labels/enhancement): Improvements to an assembly which do not add new APIs (e.g. performance improvements, code cleanup).
* [test bug](https://github.com/dotnet/corefx/labels/test%20bug): Bugs in the tests for a specific assembly.
* [test enhancement](https://github.com/dotnet/corefx/labels/test%20enhancement): Improvements in the tests for a specific assembly (e.g. improving test coverage).
* [documentation](https://github.com/dotnet/corefx/labels/documentation): Issues related to documentation (e.g. incorrect documentation, enhancement requests).
* [question](https://github.com/dotnet/corefx/labels/question): Questions about the product, source code, etc.
* **Other**:
* [up for grabs](https://github.com/dotnet/corefx/labels/up%20for%20grabs): Small sections of work which we believe are well scoped. These sorts of issues are a good place to start if you are new. Anyone is free to work on these issues.
* [needs more info](https://github.com/dotnet/corefx/labels/needs%20more%20info): Issues which need more information to be actionable. Usually this will be because we can't reproduce a reported bug. We'll close these issues after a little bit if we haven't gotten actionable information, but we welcome folks who have acquired more information to reopen the issue.
In addition to the above, we have a handful of other labels we use to help classify our issues. Some of these tag cross cutting concerns (e.g. [tenet-performance](https://github.com/dotnet/corefx/labels/tenet-performance)), whereas others are used to help us track additional work needed before closing an issue (e.g. [api-needs-exposed](https://github.com/dotnet/corefx/labels/api-needs-exposed)).
### Milestones
We use [milestones](https://github.com/dotnet/corefx/milestones) to prioritize work for each upcoming release to NuGet.org.
### Assignee
We assign each issue to assignee, when the assignee is ready to pick up the work and start working on it. If the issue is not assigned to anyone and you want to pick it up, please say so - we will assign the issue to you. If the issue is already assigned to someone, please coordinate with the assignee before you start working on it.
Note: This is a new scheme introduced in 2016/9. The old scheme used assignees as area owners. We will migrate issues to the new scheme throughout 2016.
### Areas
Areas are tracked by labels area-&#42; (e.g. area-System.Collections). Each area typically corresponds to one or more contract assemblies.
| Area | Owners / experts | Description |
|-----------------------------------------------------------------------------------------------|------------------|-------------|
| [area-Infrastructure](https://github.com/dotnet/corefx/labels/area-Infrastructure) | [@mellinoe](https://github.com/mellinoe), [@ericstj](https://github.com/ericstj), [@weshaggard](https://github.com/weshaggard) |Covers:<ul><li>Packaging</li><li>Build and test infra</li><li>VS intergation</li></ul><br/>**Triage in progress** |
| [area-Meta](https://github.com/dotnet/corefx/labels/area-Meta) | [@tarekgh](https://github.com/tarekgh) | Issues without clear association to any specific API/contract, e.g. <ul><li>new contract proposals</li><li>cross-cutting code/test pattern changes (e.g. FxCop failures)</li><li>project-wide docs</li></ul> **Triage in progress** |
| [area-Serialization](https://github.com/dotnet/corefx/labels/area-Serialization) | [@shmao](https://github.com/shmao), [@zhenlan](https://github.com/zhenlan) | Packages:<ul><li>System.Runtime.Serialization.Xml</li><li>System.Runtime.Serialization.Json</li><li>System.Private.DataContractSerialization</li><li>System.Xml.XmlSerialization</li></ul> Excluded:<ul><li>System.Runtime.Serialization.Formatters</li></ul> |
| **System contract assemblies** | | |
| [System.AppContext](https://github.com/dotnet/corefx/labels/area-System.AppContext) | [@AlexGhiondea](https://github.com/AlexGhiondea) | | |
| [System.Buffers](https://github.com/dotnet/corefx/labels/area-System.Buffers) | [@alexperovich](https://github.com/alexperovich), [@safern](https://github.com/safern) | |
| [System.CodeDom](https://github.com/dotnet/corefx/labels/area-System.CodeDom) | [@Priya91](https://github.com/Priya91) | |
| [System.Collections](https://github.com/dotnet/corefx/labels/area-System.Collections) | [@ianhays](https://github.com/ianhays) | </ul>Excluded:<ul><li>System.Array -> System.Runtime</li></ul> |
| [System.ComponentModel](https://github.com/dotnet/corefx/labels/area-System.ComponentModel) | [@safern](https://github.com/safern), [@AlexGhiondea](https://github.com/AlexGhiondea) | |
| [System.ComponentModel.DataAnnotations](https://github.com/dotnet/corefx/labels/area-System.ComponentModel.DataAnnotations) | [@lajones](https://github.com/lajones), [@divega](https://github.com/divega) | **Pending triage** |
| [System.Composition](https://github.com/dotnet/corefx/labels/area-System.Composition) | [@AlexGhiondea](https://github.com/AlexGhiondea) | |
| [System.Configuration](https://github.com/dotnet/corefx/labels/area-System.Configuration) | [@JeremyKuhne](https://github.com/JeremyKuhne) | |
| [System.Console](https://github.com/dotnet/corefx/labels/area-System.Console) | [@ianhays](https://github.com/ianhays) | |
| [System.Data](https://github.com/dotnet/corefx/labels/area-System.Data) | [@saurabh500](https://github.com/saurabh500), [@YoungGah](https://github.com/YoungGah) | |
| [System.Data.SqlClient](https://github.com/dotnet/corefx/labels/area-System.Data.SqlClient) | [@saurabh500](https://github.com/saurabh500), [@YoungGah](https://github.com/YoungGah) | **Pending triage** |
| [System.Diagnostics](https://github.com/dotnet/corefx/labels/area-System.Diagnostics) | [@joperezr](https://github.com/dotnet/joperezr) | |
| [System.Diagnostics.Process](https://github.com/dotnet/corefx/labels/area-System.Diagnostics.Process) | [@Priya91](https://github.com/Priya91) | |
| [System.Diagnostics.Tracing](https://github.com/dotnet/corefx/labels/area-System.Diagnostics.Tracing) | | **Pending triage** |
| [System.DirectoryServices](https://github.com/dotnet/corefx/labels/area-System.DirectoryServices) | [@tquerec](https://github.com/tquerec) | |
| [System.Drawing](https://github.com/dotnet/corefx/labels/area-System.Drawing) | [@alexperovich](https://github.com/alexperovich) | |
| [System.Dynamic.Runtime](https://github.com/dotnet/corefx/labels/area-System.Dynamic.Runtime) | [@VSadov](https://github.com/VSadov), [@OmarTawfik](https://github.com/OmarTawfik) | |
| [System.Globalization](https://github.com/dotnet/corefx/labels/area-System.Globalization) | [@krwq](https://github.com/krwq), [@tarekgh](https://github.com/tarekgh) | |
| [System.IO](https://github.com/dotnet/corefx/labels/area-System.IO) | [@JeremyKuhne](https://github.com/JeremyKuhne), [@ianhays](https://github.com/ianhays) | |
| [System.IO.Compression](https://github.com/dotnet/corefx/labels/area-System.IO.Compression) | [@ianhays](https://github.com/ianhays) | |
| [System.Linq](https://github.com/dotnet/corefx/labels/area-System.Linq) | [@VSadov](https://github.com/VSadov), [@OmarTawfik](https://github.com/OmarTawfik) | |
| [System.Linq.Expressions](https://github.com/dotnet/corefx/labels/area-System.Linq.Expressions) | [@VSadov](https://github.com/VSadov), [@OmarTawfik](https://github.com/OmarTawfik) | |
| [System.Linq.Parallel](https://github.com/dotnet/corefx/labels/area-System.Linq.Parallel) | [@alexperovich](https://github.com/alexperovich), [@kouvel](https://github.com/kouvel) | |
| [System.Net](https://github.com/dotnet/corefx/labels/area-System.Net) | [@davidsh](https://github.com/davidsh), [@CIPop](https://github.com/CIPop), [@Priya91](https://github.com/Priya91) | **Triage in progress** |
| [System.Net.Http](https://github.com/dotnet/corefx/labels/area-System.Net.Http) | [@davidsh](https://github.com/davidsh), [@CIPop](https://github.com/CIPop), [@Priya91](https://github.com/Priya91) | |
| [System.Net.Security](https://github.com/dotnet/corefx/labels/area-System.Net.Security) | [@davidsh](https://github.com/davidsh), [@CIPop](https://github.com/CIPop), [@Priya91](https://github.com/Priya91) | |
| [System.Net.Sockets](https://github.com/dotnet/corefx/labels/area-System.Net.Sockets) | [@davidsh](https://github.com/davidsh), [@CIPop](https://github.com/CIPop), [@Priya91](https://github.com/Priya91) | |
| [System.Numerics](https://github.com/dotnet/corefx/labels/area-System.Numerics) | [@mellinoe](https://github.com/mellinoe) | |
| [System.Reflection](https://github.com/dotnet/corefx/labels/area-System.Reflection) | [@dnlharvey](https://github.com/dnlharvey), [@AtsushiKan](https://github.com/AtsushiKan) | **Pending triage** |
| [System.Reflection.Emit](https://github.com/dotnet/corefx/labels/area-System.Reflection.Emit) | [@dnlharvey](https://github.com/dnlharvey), [@AtsushiKan](https://github.com/AtsushiKan) | **Pending triage** |
| [System.Reflection.Metadata](https://github.com/dotnet/corefx/labels/area-System.Reflection.Metadata) | [@tmat](https://github.com/tmat), [@nguerrera](https://github.com/nguerrera) | |
| [System.Resources](https://github.com/dotnet/corefx/labels/area-System.Resources) | [@ramarag](https://github.com/ramarag), [@tarekgh](https://github.com/tarekgh) | **Pending triage** |
| [System.Runtime](https://github.com/dotnet/corefx/labels/area-System.Runtime) | [@AlexGhiondea](https://github.com/AlexGhiondea), [@joperezr](https://github.com/dotnet/joperezr) | Included:<ul><li>System.Runtime.Serialization.Formatters</li><li>System.Runtime.InteropServices.RuntimeInfo</li><li>System.Array</li></ul>Excluded:<ul><li>Path -> System.IO</li><li>StopWatch -> System.Diagnostics</li><li>WebUtility -> System.Net</li></ul> |
| [System.Runtime.CompilerServices](https://github.com/dotnet/corefx/labels/area-System.Runtime.CompilerServices) | [@AlexGhiondea](https://github.com/AlexGhiondea), [@joperezr](https://github.com/dotnet/joperezr) | |
| [System.Runtime.Extensions](https://github.com/dotnet/corefx/labels/area-System.Runtime.Extensions) | [@AlexGhiondea](https://github.com/AlexGhiondea), [@joperezr](https://github.com/dotnet/joperezr) | **Pending triage** |
| [System.Runtime.InteropServices](https://github.com/dotnet/corefx/labels/area-System.Runtime.InteropServices) | [@tijoytom](https://github.com/tijoytom), [@yizhang82](https://github.com/yizhang82) | Excluded:<ul><li>System.Runtime.InteropServices.RuntimeInfo</li></ul> |
| [System.Security](https://github.com/dotnet/corefx/labels/area-System.Security) | [@bartonjs](https://github.com/bartonjs), [@steveharter](https://github.com/steveharter) | |
| System.ServiceModel | N/A | [dotnet/wcf](https://github.com/dotnet/wcf) |
| [System.ServiceProcess](https://github.com/dotnet/corefx/labels/area-System.ServiceProcess) | [@Priya91](https://github.com/Priya91) | |
| [System.Text.Encoding](https://github.com/dotnet/corefx/labels/area-System.Text.Encoding) | [@krwq](https://github.com/krwq), [@tarekgh](https://github.com/tarekgh) | |
| [System.Text.RegularExpressions](https://github.com/dotnet/corefx/labels/area-System.Text.RegularExpressions) | [@Priya91](https://github.com/Priya91) | |
| [System.Threading](https://github.com/dotnet/corefx/labels/area-System.Threading) | [@kouvel](https://github.com/kouvel), [@alexperovich](https://github.com/alexperovich) | |
| [System.Transactions](https://github.com/dotnet/corefx/labels/area-System.Transactions) | [@jimcarley](https://github.com/jimcarley), [@qizhanMS](https://github.com/qizhanMS), [@dmetzgar](https://github.com/dmetzgar) | |
| [System.Xml](https://github.com/dotnet/corefx/labels/area-System.Xml) | [@sepidehMS](https://github.com/sepidehMS), [@krwq](https://github.com/krwq) | |
| **Microsoft contract assemblies** | | |
| [Microsoft.CSharp](https://github.com/dotnet/corefx/labels/area-Microsoft.CSharp) | [@VSadov](https://github.com/VSadov), [@OmarTawfik](https://github.com/OmarTawfik) | |
| [Microsoft.VisualBasic](https://github.com/dotnet/corefx/labels/area-Microsoft.VisualBasic) | [@VSadov](https://github.com/VSadov), [@OmarTawfik](https://github.com/OmarTawfik) | |
| [Microsoft.Win32](https://github.com/dotnet/corefx/labels/area-Microsoft.Win32) | [@sepidehMS](https://github.com/sepidehMS) | |
Note: Area triage will apply the new scheme (issue types and assignee) throughout 2016.
### Triage rules - simplified
1. Each issue has exactly one **area-&#42;** label
1. Issue has no **Assignee**, unless someone is working on the issue at the moment
1. Use **up for grabs** as much as possible, ideally with a quick note about next steps / complexity of the issue
1. Set milestone to **Future**, unless you can 95%-commit you can fund the issue in specific milestone
1. Each issue has exactly one "*issue type*" label (**bug**, **enhancement**, **api-needs-work**, **test bug**, etc.)
1. Don't be afraid to say no, or close issues - just explain why and be polite
1. Don't be afraid to be wrong - just be flexible when new information appears

5
external/corefx/Documentation/project-docs/oss-signing.md vendored Normal file
View File

@@ -0,0 +1,5 @@
Open Source Signing
===================
Documentation moved to [Public Signing](public-signing.md).

BIN
external/corefx/Documentation/project-docs/pcl-targets-dialog-net46-aspnetcore10.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

91
external/corefx/Documentation/project-docs/performance-tests.md vendored Normal file
View File

@@ -0,0 +1,91 @@
Performance Tests
======================
This document contains instructions for building, running, and adding Performance tests.
Requirements
--------------------
### Windows
To run performance tests on Windows, .NET portable v5.0 is required. This library is included in [the Visual Studio Community 2015 download](https://www.visualstudio.com/products/visual-studio-community-vs). To get the correct packages during installation, follow these steps after opening the installer:
1. Select "Custom Installation" if no installation is present, or "Modify" otherwise
2. Check the "Universal Windows App Development Tools" box under the "Windows and Web Development" menu
3. Install
### Linux
Performance tests on Linux require all of the same steps as they do for regular xunit tests - see the linux instructions [here](https://github.com/dotnet/corefx/blob/master/Documentation/building/unix-instructions.md). Once you can have a directory on your Linux machine with a working corerun and xunit.console.netcore.exe (as well as the test dll containing your perf tests!), you only need to run the following command:
`dnu commands install Microsoft.DotNet.xunit.performance.runner.dnx 1.0.0-alpha-build0021 -f https://dotnet.myget.org/F/dotnet-buildtools/api/v3/index.json`
Be careful that your mscorlib, libcoreclr, and test dlls were compiled using the "/p:Configuration=Release" property. Otherwise you may get skewed results.
Running the tests
-----------
### Windows
Performance test files (if present) are stored within a library's ```tests/Performance``` directory and contain test methods that are all marked with a perf-specific *Benchmark* attribute. The performance tests will only be run if the ```performance``` property is set to ```true```.
To build and run the tests using msbuild for a project, run ```msbuild /t:BuildAndTest /p:Performance=true /p:ConfigurationGroup=Release /p:OSGroup=Windows_NT``` from the tests directory. If the v5.0 assemblies aren't installed on your system, an error will be raised and no tests will be run.
Note: Because build.cmd runs tests concurrently, it's not recommended that you execute the perf tests using it.
results will be in: corefx/bin/tests/Windows_NT.AnyCPU.Release/TESTNAME/netcoreapp1.0
### Linux
From your tests directory, run:
```
xunit.performance System.Collections.Tests.dll -trait Benchmark=true -verbose -runner ./xunit.console.netcore.exe -runnerhost ./corerun -runid System.Collections.Tests.dll-Linux -outdir results
```
This will run the perf tests for System.Collections.Tests.dll and output the results in results/System.Collections.Tests.dll-Linux.xml and results/System.Collections.Tests.dll-Linux.csv
Adding new Performance tests
-----------
Performance tests for CoreFX are built on top of xunit and [the Microsoft xunit-performance runner](https://github.com/Microsoft/xunit-performance/).
For the time being, perf tests should reside within their own "Performance" folder within the tests directory of a library (e.g. [corefx/src/System.IO.FileSystem/tests/Performance](https://github.com/dotnet/corefx/tree/master/src/System.IO.FileSystem/tests/Performance) contains perf tests for FileSystem).
Start by adding the following lines to the tests csproj:
```
<ItemGroup>
<!-- Performance Tests -->
<Compile Include="Performance\Perf.Dictionary.cs" />
<Compile Include="Performance\Perf.List.cs" />
<Compile Include="$(CommonTestPath)\System\PerfUtils.cs">
<Link>Common\System\PerfUtils.cs</Link>
</Compile>
</ItemGroup>
<!-- Optimizations to configure Xunit for performance -->
<ItemGroup>
<IncludePerformanceTests>true</IncludePerformanceTests>
</ItemGroup>
```
(Replace Dictionary/List with whatever class you’re testing.)
Next, the project.json for the tests directory also needs to import the xunit libraries:
```
"Microsoft.DotNet.xunit.performance": "1.0.0-*",
"xunit": "2.1.0",
"xunit.netcore.extensions": "1.0.0-prerelease-*"
```
Once that’s all done, you can actually add tests to the file. The basic structure of a perf test file with file name Perf.Dictionary.cs should be like so:
```
using Xunit;
using Microsoft.Xunit.Performance;
namespace System.Collections.Tests
{
public class Perf_Dictionary
{
[Benchmark]
public void ctor()
{
foreach (var iteration in Benchmark.Iterations)
using (iteration.StartMeasurement())
for (int i = 0; i < 20000; i++)
{
new Dictionary<int, string>();
}
}
}
}
```
The perf-test runner handles a lot of the specifics of the testing for you like iteration control. You won't need to add any Asserts or anything generally used in functional testing to get perf measurements, just make sure the thing within the “using” is big enough to avoid timer resolution errors.

109
external/corefx/Documentation/project-docs/porting.md vendored Normal file
View File

@@ -0,0 +1,109 @@
# Porting to .NET Core
The purpose of this document is to share the plans on how we're going to port more APIs to .NET Core.
## Summary
Compared to other .NET stacks, specifically the .NET Framework, Mono, Unity, and Xamarin the .NET Core platform doesn't expose enough APIs. This makes porting assets to .NET Core quite challenging, especially for areas which don't have replacements.
So we want to bring more APIs to .NET Core. In order to keep our promise of being open and transparent, we want to:
* Clearly communicate what we plan on porting, how we prioritize, what we don't want to port, and how we're thinking of cross-platform and compatibility.
* Avoid being the bottleneck by allowing community members to help with porting.
## Prioritization
As of today, .NET Core supports three app models:
* **ASP.NET apps and services**
* **Console apps**
* **Universal Windows Platform (UWP) apps**
We'll prioritize APIs that affect the ability to write those kind of apps over app models that .NET Core currently doesn't support (such as building desktop applications). Please note that this doesn't mean that we'll never port the other APIs -- it just means those rank lower.
The same is true for platforms: the implementation of .NET Framework only runs on Windows. Our goal for .NET Core is to support the following platforms:
* Windows
* OS X
* Linux
(Please note that that the specific version numbers, editions, and distros aren't fully finalized yet.)
While we try to be mindful of other ports actively happening (such a BSD Unix), we prioritize those three platforms. It's also worth pointing out that we generally don't prioritize within these platforms; in other words we consider them all as equals. Of course, we start from a Windows implementation so the support is currently more complete there. Also, we're mindful of the ways developers are most likely to use the platforms as well. For instance, many web developers debug and test on OS X but deploy to Linux. This guides us when prioritizing work to address point-in-time issues.
We determine which APIs are critical by leveraging various data sources:
* **Community feedback** (such as GitHub, UserVoice)
* **Partner feedback** (1st party and 3rd party applications)
* **API usage of existing applications** (such as submissions from API Port, ASP.NET applications, and Silverlight based phone apps)
We obviously aren't going to use a fixed formula to determine the stack rank of an API. We'll also leverage the experience from long term members on the team and combine it with the data and feedback to make intelligent decisions. For the sake of transparency we'll share all the data we have and the factors that lead to a specific decision. So if a decision we make is problematic for a part of the .NET ecosystem, such as not including the interfaces of ADO.NET for ORM providers, we can adjust as we go.
## Mechanics
For the most part, the source code for .NET Framework and .NET Core is disjoint. In other words, porting code to .NET Core isn't an exercise of checking a box -- it requires active work.
Here is the summary of the activities involved:
* Decide which APIs should go into .NET Core
* Assess implications on componentization (see guidelines for more details)
* Assess cross-platform impact. If necessary, find out how, and even if, the current design can be supported on all supported platforms
* Get the code onto GitHub (this includes some minor clean up, such as running the code formatting tool)
* Produce packages
* Port corresponding tests
## Porting Guidelines
Here are the high level guidelines:
* **Do not** port APIs of technologies we don't want to support moving forward (see list below).
* **Do not** port APIs marked as obsolete.
* **Consider** porting APIs even if considered legacy, problematic, or otherwise inadequate.
* **Do** factor assemblies appropriately in order to preserve the componentization, specifically:
- **Do not** add dependencies from non-legacy to legacy components.
- **Do not** expose Windows-only technologies in otherwise fully portable assemblies.
- **Do** factor large chunks of functionality that cannot be supported everywhere into their own assemblies.
- **Do** consider using tester-doer patterns if only a very small number of APIs cannot be supported in all environments.
* **Consider** using extension methods and partial facades to accelerate bringing revised APIs to the .NET Framework.
* **Avoid** making changes that result in loss of binary and/or source compatibility between the .NET Framework and .NET Core.
* **Avoid** "franken-designs" with extension methods and partial facades purely for the sake of .NET Framework compatibility.
## Unsupported Technologies
Feature owners reserve the right to call out what they don't want to support on .NET Core. Since .NET Core is a new platform, we don't want to penalize our ability to build a componentized and cross-platform stack by signing up for technologies that are expensive to bring into this world and we don't think are sensible for today's needs.
This list, while not complete, is meant as a reference point. We'll add to it as we refine our porting plan. Also, just because something is currently not implemented, doesn't imply it's intentionally unsupported. Feel free to [file an issue](https://github.com/dotnet/corefx/issues/new) to ask for specific APIs and technologies. Porting requests are generally marked as [port-to-core](https://github.com/dotnet/corefx/issues?q=is%3Aopen+is%3Aissue+label%3Aport-to-core).
Binary Serialization is supported post 1.1, however we do not support cross-platform binary serialization. For new code you may want to consider other serialization approaches such as data contract serialization, XML serialization, JSON.NET, and protobuf-net.
Technology | More information
---------------------------|-----------------------------------
AppDomains | [Details](#app_domains)
Remoting | [Details](#remoting)
Code Access Security (CAS) | [Details](#code-access-security-cas)
Security Transparency | [Details](#security-transparency)
### App Domains
**Justification**. AppDomains require runtime support and are generally quite expensive. While still implemented by CoreCLR it's not available in .NET Native and we don't plan on adding this capability.
**Replacement**. AppDomains were used for different features; for isolation we recommend processes and/or containers. For dynamic loading, we provide `AssemblyLoadContext`. Information (such as the name and base directory) is provided by APIs on other types, for instance `AppContext.BaseDirectory `. Some scenarios, such as getting the list of loaded are unsupported as they are inherently fragile.
### Remoting
**Justification**. The idea of .NET remoting -- which is transparent remote procedure calls -- has been identified as a problematic architecture. Outside of that realm, it's also used for cross AppDomain communication which is no longer supported. On top of that, remoting requires runtime support and is quite heavyweight.
**Replacement**. For communication across processes, inter-process communication (IPC) should be used, such as pipes or memory mapped files. Across machines, you should use a network based solution, preferably a low-overhead plain text protocol such as HTTP.
### Code Access Security (CAS)
**Justification**. Sand-boxing, i.e. relying on the runtime or the framework to constrain which resources a managed application can run, is considered a non-goal for .NET Core. We've already state previously that relying on sand-boxing for security reasons isn't an approach we're feeling comfortable with; there are simply too many pieces in object oriented framework that can result in elevation of privileges. Thus we don't treat CAS as security boundary anymore. On top of that, it makes the implementation more complicated and often has performance implications for the happy path.
**Replacement**. Use operating system provided security boundaries, such as user accounts for running processes with the least set of privileges.
### Security Transparency
**Justification**. Similar to CAS, this feature allows separating sand-boxed code from security critical code in a declarative fashion. This feature was heavily used by Silverlight.
**Replacement**. Use operating system provided security boundaries, such as user accounts for running processes with the least set of privileges.

4
external/corefx/Documentation/project-docs/project-nuget-dependencies.md vendored Normal file
View File

@@ -0,0 +1,4 @@
Project NuGet Dependencies
==========================
Documentation moved to [Project NuGet Dependencies](https://github.com/dotnet/buildtools/blob/master/Documentation/project-nuget-dependencies.md).

36
external/corefx/Documentation/project-docs/public-signing.md vendored Normal file
View File

@@ -0,0 +1,36 @@
Public Signing
===================
For reasons listed over on [Strong Naming](strong-name-signing.md), all .NET Core assemblies are strong-named.
To enable you to build assemblies that have a matching identity to what Microsoft would build, we leverage a new signing mechanism called _Public Signing_. This lets you clone the dotnet/corefx repository, build and then drop the resulting assembly in your application with zero changes to consuming libraries. By default, all .NET Core projects build using public signing.
Public signing is very similar to [delay signing](http://msdn.microsoft.com/en-us/library/t07a3dye(v=vs.110).aspx) but without the need to add skip verification entries to your machine. This allows you to load the assembly in most contexts, or more precisely in any context that doesn't require validating the strong-name signature.
When running on the full .NET Framework we only support using public signed assemblies for debugging and testing purposes. Microsoft does not guarantee that you can successfully load public signed assemblies in all scenarios that are required for production use. For list of known scenarios where public signing does not work when running on .NET Framework, see below.
However, in the context of ASP.NET 5 on .NET Core, or .NET Native, Microsoft supports using public signed assemblies for production uses. Make note, however, that while ability to load public signed binaries is supported on these platforms, the API and contents of the assembly itself is unsupported (due to it being privately built).
Known issues when debugging and testing public signed assemblies on .NET Framework:
- You will not be able to install the assembly to the [Global Assembly Cache (GAC)](https://msdn.microsoft.com/en-us/library/yf1d93sz.aspx)
- You will not be able to load the assembly in an AppDomain where shadow copying is turned on.
- You will not be able to load the assembly in a partially trusted AppDomain
The `corflags.exe` tool that ships with the .NET Framework SDK can show whether a binary is delay-signed or strong-named. For a delay-signed assembly it may show:
```
CorFlags : 0x20003
```
For a strong-named assembly it can show:
```
CorFlags : 0x2000b
```
The bit that is flipped is 0x8. If the bit is set, the assembly is strong-named. Additionally, the `sn.exe -vf` tool can show the same information. It will output `<assembly> is a delay-signed or test-signed assembly` or `Failed to verify assembly -- Strong name validation failed.` for a public-signed binary.
The [FakeSign package on NuGet](https://www.nuget.org/packages/fakesign) contains the `FakeSign.exe` tool that can flip the bit on or off.
Additionally, starting with Visual Studio 2015 Update 2 the C# and VB compilers support the new `/publicsign` command-line argument. You can also pass it to the compiler from your MSBuild project by setting the `<PublicSign>True</PublicSign>` MSBuild property to true. Note that you have to set `<DelaySign>False</DelaySign>` otherwise you will get an error that DelaySign and PublicSign can't be both specified at the same time.

32
external/corefx/Documentation/project-docs/repo-organization.md vendored Normal file
View File

@@ -0,0 +1,32 @@
Repo Organization
=================
Tests for a project are kept under the `tests` folder, which is a peer of the `src` folder. If you need to have multiple test projects for a component, structure them in sub folders.
For example, lay things out like this:
```
tests\
test_project_1\
test_1.cs
test_2.cs
test_project_1.csproj
test_project_2\
test_1.cs
test_2.cs
test_project_2.csproj
```
Not like this:
```
tests\
test_project_1.csproj
test_project_2.csproj
test_folder_1\
test_1.cs
test_2.cs
test_folder_2\
test_1.cs
test_2.cs
```

25
external/corefx/Documentation/project-docs/roadmap.md vendored Normal file
View File

@@ -0,0 +1,25 @@
# Roadmap for CoreFx
Related: [Overall .NET Core Roadmap](https://github.com/dotnet/core/blob/master/roadmap.md).
---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<
We need a document that outlines our vision for .NET Core:
* Startup space: highly scalable, efficient applications
* When in conflict, favor this over pure productivity
* Efficient data manipulation APIs
- Low allocation APIs
- Better blending of native code and managed code (Span, DllExport)
As the scissors indicate, these are notes for Krzysztof to fill in more details here.
Example:
## Provide a better alternative for `System.Diagnostics.Process`
Our `Process` class was designed for a time where one would drag & drop a process component on a design surface, configure it in a visual designer, and then write a line or two to launch it. Also, it was designed around many concepts that are arguably specific to the Windows platform, such as `ShellExecute`.
It seems we should take another look at this and see whether we can create a better API for dealing with processes.
---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<

1
external/corefx/Documentation/project-docs/standard-platform.md vendored Normal file
View File

@@ -0,0 +1 @@
this document has moved to [net-platform-standard.md](../architecture/net-platform-standard.md)

24
external/corefx/Documentation/project-docs/strong-name-signing.md vendored Normal file
View File

@@ -0,0 +1,24 @@
Strong Name Signing
===================
All .NET Core assemblies are [strong-named](http://msdn.microsoft.com/en-us/library/wd40t7ad.aspx). We do this for two reasons:
1. _Compatibility_. We want to maintain type identity with previous versions of our assemblies that have shipped across various versions of our platforms. Removing a strong-name from an assembly is a breaking change, and would break the ability to consume and run libraries built against the previous identities.
2. _Serviceability_. When running on .NET Framework some of .NET Core assemblies ship locally ("app-local") with the application, this is in contrast to other framework assemblies that are placed in the [GAC](http://msdn.microsoft.com/en-us/library/yf1d93sz.aspx). To be able to service these libraries for critical security updates, we make use of the [app-local servicing](http://blogs.msdn.com/b/dotnet/archive/2014/01/22/net-4-5-1-supports-microsoft-security-updates-for-net-nuget-libraries.aspx) feature which requires that assemblies have strong-names.
## FAQ
### 1. Microsoft strong-names their assemblies, should I?
For the most part, the majority of applications and libraries do not need strong-names. Strong-names are left over from previous eras of .NET where [sandboxing](http://en.wikipedia.org/wiki/Sandbox_(computer_security)) needed to differentiate between code that was trusted, versus code that was untrusted. However in recent years, sandboxing via AppDomains, especially to [isolate ASP.NET web applications] (http://support.microsoft.com/kb/2698981), is no longer guaranteed and is not recommended.
However, strong-names are still required in some rare situations, most of which are called out on this page: [Strong-Named Assemblies](http://msdn.microsoft.com/en-us/library/wd40t7ad.aspx).
### 2. I really, _really_ need to strong-name, what kinds of issues will I run into?
There are three major problems that developers run into after strong naming their assemblies:
1. _Binding Policy_. When developers talk about strong-names, they are usually conflating it with the strict binding policy of the .NET Framework that kicks in _when_ you strong-name. This binding policy is problematic because it forces, by default, an exact match between reference and version, and requires developers to author complex [binding redirects](http://msdn.microsoft.com/en-us/library/eftw1fys.aspx) when they don't. In recent versions of Visual Studio, however, we've added [Automatic Binding Redirection](http://msdn.microsoft.com/en-us/library/2fc472t2.aspx) as an attempt to reduce pain of this policy on developers. On top of this, all newer platforms, including _Silverlight_, _WinRT-based platforms_ (Phone and Store), _.NET Native_ and _ASP.NET 5_ this policy has been loosened, allowing later versions of an assembly to satisfy earlier references, thereby completely removing the need to ever write binding redirects on those platforms.
2. _Virality_. Once you've strong-named an assembly, you can only statically reference other strong-named assemblies.
3. _No drop-in replacement_. This is a problem for open source libraries where the strong-name private key is not checked into the repository. This means that developers are unable to build to their own version of the library and then use it as a drop-in replacement without recompiling _all_ consuming libraries up stack to pick up the new identity. This is extremely problematic for libraries, such as Json.NET, which have large incoming dependencies. Firstly, we would recommend that these open source projects check-in their private key (remember, [strong-names are used for identity, and not for security](http://msdn.microsoft.com/en-us/library/wd40t7ad.aspx)). Failing that, however, we've introduced a new concept called [Public Signing](public-signing.md) that enables developers to build drop-in replacements without needing access to the strong-name private key. This is the mechanism that .NET Core libraries use by default.

32
external/corefx/Documentation/project-docs/support-dotnet-core-instructions.md vendored Normal file
View File

@@ -0,0 +1,32 @@
# Making your libraries compatible with .NET Core and other .NET Platforms
Want to make your libraries multi-platform? Want to see how much work is required to make your application compatible with other .NET platforms? The [**.NET Portability Analyzer**](http://github.com/microsoft/dotnet-apiport) is a tool that provides you with a detailed report ([example report](http://dotnet.github.io/port-to-core/Moq4_ApiPortabilityAnalysis.htm)) on how portable your code is across .NET platforms by analyzing assemblies. The Portability Analyzer is offered as a Visual Studio Extension and as a console app.
## New Targets
- [.NET Core 5](https://www.dotnetfoundation.org/netcore): Has a modular design, employs side-by-side, and targets cross-platform scenarios. Side-by-side allows you to adopt new .NET Core versions without breaking other apps.
- [ASP.NET 5](https://www.dotnetfoundation.org/aspnet-5): is a modern web-framework built on .NET Core 5 thus giving developers the same benefits.
- [.NET Native](http://blogs.msdn.com/b/dotnet/archive/2014/04/24/dotnetnative-performance.aspx): Improve performance of your Windows Store apps that run on x64 and ARM machines by using .NET Native's static compilation.
## How to Use Portability Analyzer
To begin using the .NET Portability Analyzer, download the extension from the Visual Studio Gallery. You can configure it in Visual Studio via *Tools* >> *Options* >> *.NET Portability Analyzer* and select your Target Platforms. For now, please use ASP.NET 5 as a proxy for all .NET Core 5-based platforms (e.g. [Windows 10 .NET UAP apps](http://blogs.windows.com/buildingapps/2015/03/02/a-first-look-at-the-windows-10-universal-app-platform/)).
![](../images/portability_screenshot.png)
To analyze your entire project, right-click on your project in the Solution Explorer and select *Analyze* >> *Analyze Assembly Portability*. Otherwise, go to the Analyze menu and select *Analyze Assembly Portability*. From there, select your project's executable or .dll.
![](../images/portability_solution_explorer.png)
After running the analysis, you will see your .NET Portability Report. Only types that are unsupported by a target platform will appear in the list and you can review recommendations in the **Messages** tab in the **Error List**. You can also jump to problem areas directly from the **Messages** tab.
![](../images/portability_report.png)
Don't want to use Visual Studio? You can also use the Portability Analyzer from the Command Prompt. Download the command-line analyzer [here](http://github.com/microsoft/dotnet-apiport/releases).
- Type the following command to analyze the current directory: `ApiPort.exe analyze -f . `
- To analyze a specific list of .dlls type the following command: `ApiPort.exe analyze -f first.dll -f second.dll -f third.dll`
Your .NET Portability Report will be saved as an Excel .xlsx file in your current directory. The **Details** tab in the Excel Workbook will contain more info.
For more info on the .NET Portability Analyzer, read the [documentation](https://github.com/Microsoft/dotnet-apiport/blob/master/docs/HowTo/Introduction.md).

Some files were not shown because too many files have changed in this diff Show More