search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.63k stars 25.3k forks source link

Enhance WS topic with FDD scenario #9214

Closed natemcmaster closed 5 years ago

natemcmaster commented 6 years ago

This article currently specifies that self-contained is required, which is not exactly true. Framework-dependent apps can be used to run Windows services as well. With .NET Core 2.0 and older, this requires setting up the service to run dotnet.exe foo.dll. With .NET Core 2.1 and newer, users have an additional option -- framework dependent executables (foo.exe). In the 2.1 SDK, this feature is opt in (<UseAppHost>true</UseAppHost>). In the 2.2 SDK, this will be on by default. https://github.com/dotnet/sdk/pull/2462

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

guardrex commented 6 years ago
  1. What's the recommendation for 2.1 or earlier? Should we just link over to the App deployment topic, where the pros and cons of each are described and let the dev base their decision on that content?
  2. WRT FDE (since 2.1): Is that only available for services and not available for other deployments of .NET Core apps? Is there a plan to cover FDE in the App deployments topic (AFAICT there's no issue on dotnet/docs for it)?
  3. WRT scheduling: Is this more of a 'we need it soon' (weeks), or can this wait until later in the year?

cc: @shirhatti

natemcmaster commented 6 years ago
  1. I think linking to that deployment doc and helping people understand the tradeoffs is good enough. There are advantages each way: isolation vs servicing, app size vs dependencies, etc.
  2. FDE: I also didn't see anything in https://github.com/dotnet/docs/issues on the subject. @peterhuene @livarcocc are there already plans to document framework dependent executables?
  3. IMO later this year is fine. There is nothing wrong with doing self-contained apps as a Windows service. It's just a little misleading that the doc says it is required.
Rick-Anderson commented 6 years ago

@guardrex focus on 2.1 and later for the first update.

guardrex commented 5 years ago

@natemcmaster I'm starting work on this one today. I'm still wondering about the FDE scenario. I should be able to get it in here. Without FDE coverage in the deployment topic, I don't have anything to point to for dev guidance for that scenario. I'll need to carry a little bit of deployment content here to cover that scenario.

@mairaw, Hola! :wave: ...... AFAICT, there's no issue to document the "framework-dependent executable (FDE)" scenario in .NET Core application deployment. Should there be an issue, or will FDE not be covered (or at least not for the foreseeable future)?

Another option is not to cover FDE with the FDD updates here. However, that just produces an issue to replace this one. I'd like to see the issue count go down ... not sideways.

guardrex commented 5 years ago

@natemcmaster I think I'll stick to "FDD" language on the first pass of updates as much as possible. My thinking is that FDE is a type of FDD. The sample will be 2.2, thus an FDE by default. I'll see if I can make a passing remark about the difference without confusing the subject.

We also probably need to be careful with "FDE" ...

... breaks the pattern ("deployment"). It's probably more like ...

🙈 plz no 🙉 ... I'll let the experts work it out, but "FDE" doesn't capture "deployment" in the naming.

[EDIT] Also, I can't find MSBuild doc info on <SubType> for <Compile>. I'll keep looking, but let me know if u have info.

<Compile Update="CustomWebHostService.cs">
  <SubType>Component</SubType>
</Compile>

I plan to say the following ...

Set a Component subtype on the file that contains the \ implementation:

natemcmaster commented 5 years ago

@guardrex

Another option is not to cover FDE with the FDD updates here.

I wouldn't attempt to completely explain the framework-dependent executables in this aspnet doc. That seems like something the dotnet/docs team should handle since this feature applies to all .NET Core projects, not just aspnet. I don't have all the details on this feature and what it should be named in documentation, but @livarcocc @peterhuene @kathleendollard may be able to help.

guardrex commented 5 years ago

I'm trying the most minimal coverage that I can get away with ... something like (note that the topic is versioned for 2.2+, so we don't need to sweat <UseAppHost>) ...

When the FDD scenario is used with an ASP.NET Core app, the SDK produces an assembly (library) file (*.dll) that's run with the dotnet command. When the FDD scenario is used with an ASP.NET Core Windows Service app, the SDK produces an executable (*.exe), called a framework-dependent executable.

Other than listing the two deployment scenarios, I don't say anything else. I refer the reader to the .NET Core doc on the subject.

[I just typed that out ... so the paint isn't dry on it yet. We can strike or update it on review.]

natemcmaster commented 5 years ago

Sounds good to me. 👍

guardrex commented 5 years ago

@natemcmaster WRT FDE ...

framework dependent executables (foo.exe) ... In the 2.1 SDK, this feature is opt in (true). In the 2.2 SDK, this will be on by default. dotnet/sdk#2462

If I only use the netcoreapp2.2 TFM with the 2.2.0-preview3 SDK ...

<PropertyGroup>
  <TargetFramework>netcoreapp2.2</TargetFramework>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

... and publish ...

dotnet publish --configuration Release --output c:\\svc

I do get an FDD, but I don't get an FDE ...

capture

If I add the <UseAppHost> prop, the SDK demands that I provide an RID. When I provide the RID, it publishes with an executable. It also publishes with an EXE if I only add the RID. However in both of those cases, it doesn't publish as an FDD/FDE ... it publishes an SCD. This is in spite of using the same dotnet publish command without an RID.

If I provide an RID AND the <SelfContained> switch set to false ...

<PropertyGroup>
  <TargetFramework>netcoreapp2.2</TargetFramework>
  <SelfContained>false</SelfContained>
  <RuntimeIdentifier>win7-x64</RuntimeIdentifier>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

... and publish ...

dotnet publish --configuration Release --output c:\\svc

... the output is what I'm looking for ...

capture

Idk if that runs yet ... I think it will run ... I'll find out in a few minutes. 🤞

[EDIT] :tada: Yes! 🎈 ... It ✨ Just Works!:tm: ✨

Is that the correct FDE guidance? ... provide the <SelfContained> switch set to false and an RID?

Side-question: I like using the Sdk.Web for its helpful publishing characteristics. However, this isn't a web app. I don't like seeing the web.config come out. Thus far, I'm tossing in ye olde <IsTransformWebConfigDisabled> set to false. Are you ok with that?

natemcmaster commented 5 years ago

Is that the correct FDE guidance? ... provide the <SelfContained> switch set to false and an RID?

It appears that is what is required to generate a framework dependent executable. I'll let @peterhuene @nguerrera and @livarcocc say whether the guidance is the intended usage or not: FDE is an SDK feature that they worked on.

nguerrera commented 5 years ago

That is correct for 2.x. In 3.0, there is an inferred default runtime identifier, but for 2.x, you have to supply the runtime identifier and opt out of self-contained.

guardrex commented 5 years ago

@nguerrera Thanks ... and that's good news really because I guessed on the PR to go that way. I'm going to open a 3.0 docs issue referencing this convo so the docs team doesn't lose track of it.

@natemcmaster I guess we can proceed with review if you have more updates. I'll wait tho to hear back from Sourabh on the <SubType>Component</SubType> component bit.

mairaw commented 5 years ago

Sorry I didn't respond sooner. Yes, I believe we should document that for .NET Core.

/cc @rpetrusha since he owns the deployment topics