Update core/porting/libraries #2467

guardrex · 2017-06-21T21:53:30Z

Also waiting on TFS#: 1023634 CI Build reports valid API xref links as invalid
Invisible zero-width spaces! Arrrrrrrr!

Fixes #2255

guardrex · 2017-06-30T20:58:58Z

😅Finally!

@mairaw @cartermp It probably needs a little work. For sure, there are a few spots for special attention because I either wasn't sure or concerned:

Is the pre-req "reading list" at the top of the topic the best prep for porting libraries?
"are generally quite expensive" and "which is expensive to maintain" language ... seems somewhat unspecific. Can someone say more precisely why these were expensive? Or, does that just not really matter? (i.e., the decision was made, it's gone, forget about it, etc.)
RE: CAS "correctness-performance implications for applications" ... I looked up "correctness-performance," and it looks like its a real thing, but I ask: Are the consumers of this topic going to know what that means? Can we link something to that for more info?
"Security Transparency" for Silverlight. The original text said it "was" used. I changed to "is." Is that a fair change? Is Security Transparency still used in Silverlight apps?

svick · 2017-07-03T19:47:46Z

docs/core/porting/libraries.md


-Read more in [.NET Platform Standard Library](../../standard/net-standard.md).
+Just because an API or technology isn't currently implemented doesn't imply it's intentionally unsupported. Feel free to file an issue in the [dotnet/corefx repository issues](https://github.com/dotnet/corefx/issues) at GitHub to ask for specific APIs and technologies. [Porting requests in the issues](https://github.com/dotnet/corefx/labels/port-to-core) are usually marked with the `port-to-core` label.


[Porting requests in the issues](https://github.com/dotnet/corefx/labels/port-to-core) are usually marked with the `port-to-core` label.

Why is the first part of the sentence linked, instead of the more obvious "the port-to-core label". That way, it's clear where the link leads, especially considering the "usually".

My intent was to avoid the the link looking like it lands on content that describes the label; it goes to the issues that are marked port-to-core. "Porting requests in the issues" is what the landing page provides if they click the link.

However, I do think this sentence is blown (as you say: especially considering the "usually"): If the link goes to port-to-core tagged issues, then "usually" doesn't work here.

I'm going to to refactor this sentence on the next commit.

I looked this over. Issues for porting requests should be marked port-to-core, and there's no point saying that it should "usually" be the case. I can't tell the reader how to find the other issues that aren't marked port-to-core. The simplest way to deal with this is just to remove the word "usually." That makes the sentence a true statement (even if the request was generated internally), and the link provides the content described by the text: "Porting requests in the issues" describes the landing page content. I'm open to suggestions tho, so if you can think of a better way to express the same thought, I'm all 👂👂👂👂👂👂.

Yeah, this looks good to me. I don't have a better way to express it.

svick · 2017-07-03T19:52:43Z

docs/core/porting/libraries.md


-### App Domains
+For code isolation, we recommend separate processes or using containers as an alternative. For the dynamic loading of assemblies, we recommend the new <xref:System.Runtime.Loader.AssemblyLoadContext> class. 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 assemblies, are unsupported, as they're inherently fragile.


The examples of AppDomain.BaseDirectory and AppDomain.GetAssemblies() are coming back with .Net Core 2.0. Is it okay that this document is going to again become outdated soon?

We don't have the ability to deal cleanly with versions just yet. I can add "in 1.0" and "for 2.0" language tho. I'm going to ping the CoreFX cats for a word on this, since this is really their content.

svick · 2017-07-03T19:53:02Z

docs/core/porting/libraries.md


-### App Domains
+For code isolation, we recommend separate processes or using containers as an alternative. For the dynamic loading of assemblies, we recommend the new <xref:System.Runtime.Loader.AssemblyLoadContext> class. 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 assemblies, are unsupported, as they're inherently fragile.


Why is AppContext.BaseDirectory code and not xref?

svick · 2017-07-03T20:17:57Z

docs/core/porting/libraries.md


-AppDomains can be used for different purposes on the .NET Framework. For code isolation, we recommend separate processes and/or containers as an alternative. For dynamic loading of assemblies, we recommend the new @System.Runtime.Loader.AssemblyLoadContext class.
+To make code migration from .NET Framework easier, we've exposed some of the <xref:System.AppDomain> API surface in .NET Core. Some of the APIs function normally (for example, <xref:System.AppDomain.UnhandledException?displayProperty=fullName>), some of them do nothing (for example, <xref:System.AppDomain.SetCachePath%2A>), and some of them throw <xref:System.PlatformNotSupportedException> (for example, <xref:System.AppDomain.CreateDomain%2A>).


I'm confused, as far as I can tell, this paragraph describes the situation as of .Net Core 2.0, but the previous one seems to be about .Net Core 1.x.

@svick Yes, that's correct ... 2.0. I'm going to add "for .NET Core 2.0" language.

@karelz @weshaggard Can you suggest the cleanest split between 1.0 and 2.0 content here? This content was taken (shamelessly stolen actually 😜) from your CoreFX porting doc.

svick · 2017-07-03T20:19:49Z

docs/core/porting/libraries.md

-* @System.Runtime.Serialization.DataContractSerializer for both XML and JSON
-* @System.Xml.Serialization.XmlSerializer for XML
-* [protobuf-net](https://github.com/mgravell/protobuf-net) for Protocol Buffers
+.NET Remoting, which is transparent remote procedure calls, was identified as a problematic architecture. It's used for cross-AppDomain communication, which is no longer supported. Also, Remoting requires runtime support, which is expensive to maintain. For these reasons, .NET Remoting isn't supported on .NET Core.


.NET Remoting, which is transparent remote procedure calls, …

I think the grammar doesn't quite work here.

There's nothing wrong with a non-essential clause after a noun. However, I don't care for "which is" either. Let's drop the non-essential clause.

I meant that ".Net Remoting is calls" doesn't sound like correct grammar to me.

You mean this? ......

.NET Remoting, which is transparent remote procedure calls, was identified as a problematic architecture.

... "which is transparent remote procedure calls" is a subordinate, non-essential clause (has a subject and a predicate but doesn't make sense without an object) describing ".NET Remoting" and set off by a comma before and after. Technically, it's ok. I think it sounds like CRAP 😄 lol. Best thing to do here is 🔪 cut that out. If the reader needs to see what it means, they can search it (or we could link to .NET Remoting if you think that's a better solution).

svick · 2017-07-03T20:44:39Z

docs/core/porting/libraries.md


-### Sandboxes
+Across machines, use a network-based solution as an alternative. Preferably, use a low-overhead plain text protocol, such as HTTP. The [Kestrel web server](https://docs.microsoft.com/aspnet/core/fundamentals/servers/kestrel), the web server used by ASP.NET Core, is an option here. Consider <xref:System.Net.Sockets>. For more options, see [.NET Open Source Developer Projects: Messaging](https://github.com/Microsoft/dotnet/blob/master/dotnet-developer-projects.md#messaging).


The "Consider Sockets." sentence sounds out of place to me here.

I'll expand the sentence to make it more "conversational," but that's a guidance they provided in the CoreFX topic, so I'm inclined to leave it here as an option for the reader to explore.

svick · 2017-07-03T20:51:01Z

docs/core/porting/libraries.md

-## Retargeting your .NET Framework Code to .NET Framework 4.6.2
-
-If your code is not targeting .NET Framework 4.6.2, it's recommended that you retarget. This ensures that you can use the latest API alternatives for cases where the .NET Standard can't support existing APIs.
+If your code isn't targeting .NET Framework 4.6.2, we recommended that you retarget. This ensures the availability of the latest API alternatives for cases where the .NET Standard doesn't support existing APIs.


Is this suggesting to use 4.6.2 or newer, 4.6.2 or older, or always exactly 4.6.2? I think that should be clarified.

guardrex · 2017-07-03T21:26:03Z

@svick 👍 Cool ..... I'll get back to you soon. I'm on a priority work assignment for a few days and hope to have it squared away in a few days.

BillWagner

Overall this looks great. @guardrex I left a few comments. I'm also asking @richlander or another PM to review and make sure our guidance is accurate.

BillWagner · 2017-07-11T14:21:05Z

docs/core/porting/libraries.md


-Read more in [.NET Platform Standard Library](../../standard/net-standard.md).
+Just because an API or technology isn't currently implemented doesn't imply it's intentionally unsupported. Feel free to file an issue in the [dotnet/corefx repository issues](https://github.com/dotnet/corefx/issues) at GitHub to ask for specific APIs and technologies. [Porting requests in the issues](https://github.com/dotnet/corefx/labels/port-to-core) are marked with the `port-to-core` label.


I would remove "Feel free to" from the second sentence.

BillWagner · 2017-07-11T14:22:39Z

docs/core/porting/libraries.md


-AppDomains can be used for different purposes on the .NET Framework. For code isolation, we recommend separate processes and/or containers as an alternative. For dynamic loading of assemblies, we recommend the new @System.Runtime.Loader.AssemblyLoadContext class.
+To make code migration from .NET Framework easier, we've exposed some of the <xref:System.AppDomain> API surface in .NET Core. Some of the APIs function normally (for example, <xref:System.AppDomain.UnhandledException?displayProperty=fullName>), some of them do nothing (for example, <xref:System.AppDomain.SetCachePath%2A>), and some of them throw <xref:System.PlatformNotSupportedException> (for example, <xref:System.AppDomain.CreateDomain%2A>).


You should add a sentence about where to find which classes and APIs take which action (even if it is the obvious "check the types you use for details".)

BillWagner · 2017-07-11T14:23:48Z

docs/core/porting/libraries.md

-* @System.Runtime.Serialization.DataContractSerializer for both XML and JSON
-* @System.Xml.Serialization.XmlSerializer for XML
-* [protobuf-net](https://github.com/mgravell/protobuf-net) for Protocol Buffers
+.NET Remoting was identified as a problematic architecture. It's used for cross-AppDomain communication, which is no longer supported. Also, Remoting requires runtime support, which is expensive to maintain. For these reasons, .NET Remoting isn't supported on .NET Core.


For consistency, this should add the sentence "we don't plan on adding support in the future" as you did above, if it applies.

guardrex · 2017-07-11T17:24:24Z

@BillWagner For System.AppDomain, I refer them to ref source. I'm not sure what else to tell the dev to do there. We don't want to list everything, nor is there another topic that does so AFAICT, correct?

BillWagner · 2017-07-12T13:51:05Z

@guardrex

For System.AppDomain, I refer them to ref source. I'm not sure what else to tell the dev to do there. We don't want to list everything, nor is there another topic that does so AFAICT, correct?

That is correct. I was looking for a statement to check each API for specifics.

Also, we now have merge conflicts. 😭 Can you rebase to address those?

guardrex · 2017-07-12T17:54:32Z

@BillWagner I'm a little confused on the "check each API" part of ...

I was looking for a statement to check each API for specifics.

That section only pertains to System.AppDomain. I just made a small change along these lines where it said "APIs" (plural) before. Now, it reads (with "API" referring solely to System.AppDomain) ...

Some of the API functions normally (example), some members do nothing (example), and some of them throw <xref:System.PlatformNotSupportedException> (example).

Are you saying "was looking" in the sense that the update did the trick, or do you mean "was looking" and it still needs work?

BillWagner · 2017-07-14T14:12:29Z

@guardrex The changes you've made addressed the concerns I had. When I read "some methods do nothing and some throw exceptions", I need to know where to find which do which action to be productive. By pointing readers to that location, we've anticipated that question and given an answer.

guardrex · 2017-07-15T20:55:08Z

Just heard (and then looked at the source to confirm) from @[DamianEdwards] on the 3/28 Community Standup (31:13) that obtaining a list of loaded assemblies was restored since this topic was originally written. I've removed the offending line on the last commit.

[EDIT] Looking further: @BillWagner It prob needs another change. I don't like this language (at least written this way) ...

Information (such as the name and base directory) is provided by APIs on other types, for instance xref:AppContext.BaseDirectory%2A.

... due to the presence of ...

https://github.com/dotnet/corefx/blob/master/src/System.Runtime.Extensions/src/System/AppDomain.cs#L27

and

https://github.com/dotnet/corefx/blob/master/src/System.Runtime.Extensions/src/System/AppDomain.cs#L42-L49

Since we say to look at the API and provide a nice, low-barrier link to it, how about we strike that line, too?

guardrex · 2017-07-17T23:30:00Z

Ok, I'm done ...... unless anyone has something. It's about time for this chick 🐤 to fly the coop.

Luke Latham added 2 commits June 20, 2017 13:35

Update porting/libraries to MSBuild/csrpoj

f00fd1f

Update porting libraries topic

58c3990

guardrex added the WIP label Jun 21, 2017

guardrex self-assigned this Jun 21, 2017

dnfclas added the cla-already-signed label Jun 21, 2017

guardrex and others added 4 commits June 21, 2017 16:56

Merge branch 'master' into guardrex/class-lib-pj-to-csproj-update

29300a3

Minor update

92c15f0

Kill zero-width spaces in links

171146c

Updates

8870e88

guardrex closed this Jun 29, 2017

guardrex reopened this Jun 29, 2017

dnfclas added the cla-already-signed label Jun 29, 2017

guardrex closed this Jun 29, 2017

guardrex reopened this Jun 29, 2017

dnfclas added the cla-already-signed label Jun 29, 2017

guardrex closed this Jun 30, 2017

guardrex reopened this Jun 30, 2017

dnfclas added the cla-already-signed label Jun 30, 2017

Updates

85e025b

guardrex changed the title ~~[WIP] Update core/porting/libraries~~ Update core/porting/libraries Jun 30, 2017

guardrex removed the WIP label Jun 30, 2017

svick reviewed Jul 3, 2017

View reviewed changes

React to feedback

0716b56

BillWagner requested changes Jul 11, 2017

View reviewed changes

BillWagner requested a review from richlander July 11, 2017 14:35

React to feedback

5dec428

guardrex and others added 2 commits July 12, 2017 08:53

Merge branch 'master' into guardrex/class-lib-pj-to-csproj-update

fbe76a0

Minor wording change

08d513b

guardrex and others added 3 commits July 14, 2017 09:47

Merge branch 'master' into guardrex/class-lib-pj-to-csproj-update

d760bc6

Remove remark on obtaining assembly list

47462f6

Merge branch 'master' into guardrex/class-lib-pj-to-csproj-update

00d34f7

Remove one line

a00994b

BillWagner approved these changes Jul 19, 2017

View reviewed changes

guardrex merged commit a74d156 into dotnet:master Jul 19, 2017

guardrex deleted the guardrex/class-lib-pj-to-csproj-update branch July 19, 2017 15:44

omajid mentioned this pull request Jun 27, 2018

Remove a pointless mention of global.json #6150

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update core/porting/libraries #2467

Update core/porting/libraries #2467

guardrex commented Jun 21, 2017 •

edited

Loading

guardrex commented Jun 30, 2017

svick Jul 3, 2017

guardrex Jul 6, 2017

guardrex Jul 6, 2017

svick Jul 6, 2017

svick Jul 3, 2017

guardrex Jul 6, 2017

svick Jul 3, 2017

svick Jul 3, 2017

guardrex Jul 6, 2017

svick Jul 3, 2017

guardrex Jul 6, 2017

svick Jul 6, 2017

guardrex Jul 6, 2017

svick Jul 3, 2017

guardrex Jul 6, 2017

svick Jul 3, 2017

guardrex commented Jul 3, 2017

BillWagner left a comment

BillWagner Jul 11, 2017

BillWagner Jul 11, 2017

BillWagner Jul 11, 2017

guardrex commented Jul 11, 2017 •

edited

Loading

BillWagner commented Jul 12, 2017

guardrex commented Jul 12, 2017

BillWagner commented Jul 14, 2017

guardrex commented Jul 15, 2017 •

edited

Loading

guardrex commented Jul 17, 2017


		Read more in [.NET Platform Standard Library](../../standard/net-standard.md).
		Just because an API or technology isn't currently implemented doesn't imply it's intentionally unsupported. Feel free to file an issue in the [dotnet/corefx repository issues](https://github.com/dotnet/corefx/issues) at GitHub to ask for specific APIs and technologies. [Porting requests in the issues](https://github.com/dotnet/corefx/labels/port-to-core) are usually marked with the `port-to-core` label.


		### App Domains
		For code isolation, we recommend separate processes or using containers as an alternative. For the dynamic loading of assemblies, we recommend the new <xref:System.Runtime.Loader.AssemblyLoadContext> class. 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 assemblies, are unsupported, as they're inherently fragile.


		AppDomains can be used for different purposes on the .NET Framework. For code isolation, we recommend separate processes and/or containers as an alternative. For dynamic loading of assemblies, we recommend the new @System.Runtime.Loader.AssemblyLoadContext class.
		To make code migration from .NET Framework easier, we've exposed some of the <xref:System.AppDomain> API surface in .NET Core. Some of the APIs function normally (for example, <xref:System.AppDomain.UnhandledException?displayProperty=fullName>), some of them do nothing (for example, <xref:System.AppDomain.SetCachePath%2A>), and some of them throw <xref:System.PlatformNotSupportedException> (for example, <xref:System.AppDomain.CreateDomain%2A>).


		### Sandboxes
		Across machines, use a network-based solution as an alternative. Preferably, use a low-overhead plain text protocol, such as HTTP. The [Kestrel web server](https://docs.microsoft.com/aspnet/core/fundamentals/servers/kestrel), the web server used by ASP.NET Core, is an option here. Consider <xref:System.Net.Sockets>. For more options, see [.NET Open Source Developer Projects: Messaging](https://github.com/Microsoft/dotnet/blob/master/dotnet-developer-projects.md#messaging).

Update core/porting/libraries #2467

Update core/porting/libraries #2467

Conversation

guardrex commented Jun 21, 2017 • edited Loading

guardrex commented Jun 30, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Jul 3, 2017

BillWagner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Jul 11, 2017 • edited Loading

BillWagner commented Jul 12, 2017

guardrex commented Jul 12, 2017

BillWagner commented Jul 14, 2017

guardrex commented Jul 15, 2017 • edited Loading

guardrex commented Jul 17, 2017

guardrex commented Jun 21, 2017 •

edited

Loading

guardrex commented Jul 11, 2017 •

edited

Loading

guardrex commented Jul 15, 2017 •

edited

Loading