Merge pull request #1045 from microsoft/readme

Add package README specifically for nuget.org

src/Microsoft.Windows.CsWin32/Microsoft.Windows.CsWin32.nuspec

@@ -59,7 +59,7 @@
     <file src="$BaseOutputPath$System.Text.Json.dll" target="analyzers\cs\System.Text.Json.dll" />
     <file src="$BaseOutputPath$System.Text.Encodings.Web.dll" target="analyzers\cs\System.Text.Encodings.Web.dll" />
     <file src="readme.txt" target="readme.txt" />
-    <file src="..\..\README.md" target="README.md" />
+    <file src="README.md" target="README.md" />
     <file src="..\..\NOTICE.txt" target="NOTICE.txt" />
     <file src="build\**" target="build\" />
     <file src="tools\**" target="tools\" />

src/Microsoft.Windows.CsWin32/README.md

@@ -0,0 +1,37 @@
+# Automated generation of C# bindings for the Win32 API
+
+Get immediate access to the full Win32 API from C#, just by naming the APIs you require.
+Generated APIs will be accurate for your CPU architecture and target Windows version.
+All APIs are generated directly into your project, allowing you to ship without any additional runtime dependencies.
+
+Reach functionality that .NET doesn't expose via the Base Class Library (BCL) to give your library or application that feature that really sets it apart.
+
+Install this package, then create a NativeMethods.txt file with a list of any APIs you need for example:
+
+NativeMethods.txt:
+
+```
+CreateFile
+IUIRibbon
+S_OK
+NTSTATUS
+IsPwrHibernateAllowed
+ISpellChecker
+``````
+
+Any supporting APIs (e.g. enums, structs) are automatically generated when they are required by what you've directly asked for.
+
+Call extern methods through the `PInvoke` class
+
+```cs
+using SafeHandle f = PInvoke.CreateFile(
+    "some.txt",
+    (uint)GENERIC_ACCESS_RIGHTS.GENERIC_READ,
+    FILE_SHARE_MODE.FILE_SHARE_READ,
+    lpSecurityAttributes: null,
+    FILE_CREATION_DISPOSITION.CREATE_ALWAYS,
+    FILE_FLAGS_AND_ATTRIBUTES.FILE_ATTRIBUTE_NORMAL,
+    hTemplateFile: null);
+```
+
+Learn more from [our README on GitHub](https://github.com/microsoft/CsWin32#readme).

src/Microsoft.Windows.CsWin32/readme.txt

@@ -5,6 +5,21 @@ This package contains a source generator to add a user-defined set of Win32 P/In
 methods and supporting types to a C# project.
 
 To get started, create a "NativeMethods.txt" file in your project directory
-that lists the names of methods for which you need P/Invoke methods generated, one per line.
+that lists the names of Win32 APIs for which you need to have generated, one per line.
+
+Tips
+----
+
+Remove the `IncludeAssets` metadata from the package reference so that you get better code generation
+by allowing nuget to bring in the `System.Memory` package as a transitive dependency.
+
+```diff
+ <PackageReference Include="Microsoft.Windows.CsWin32" Version="0.1.647-beta">
+   <PrivateAssets>all</PrivateAssets>
+-  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+ </PackageReference>
+```
+
+Your project must allow unsafe code to support the generated code that will likely use pointers.
 
 Learn more from our README on GitHub: https://github.com/microsoft/CsWin32#readme