Add a README in nuspec (#1377)

* Add readme path from cproj and add it in nuspec * Using the existing README.md instead of creating another one
OData · Jan 7, 2025 · e4a65ae · e4a65ae
1 parent 83c7120
commit e4a65ae
Show file tree

Hide file tree

Showing 4 changed files with 170 additions and 83 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# ASP.NET Core OData 8.x
+# ASP.NET Core OData
 ---
 
 Component | Build  | Status 
@@ -7,9 +7,168 @@ ASP.NET Core OData|Rolling | [![Build Status](https://identitydivision.visualstu
 ASP.NET Core OData|Nightly | [![Build Status](https://identitydivision.visualstudio.com/OData/_apis/build/status%2FAspNetCoreOData%2FAspNetCoreOData-main-nightly-1ES?repoName=OData%2FAspNetCoreOData&branchName=main)](https://identitydivision.visualstudio.com/OData/_build/latest?definitionId=2404&repoName=OData%2FAspNetCoreOData&branchName=main)
 .NET Foundation|Release|[![Build status](https://dev.azure.com/dotnet/OData/_apis/build/status/AspNetCoreOData/AspNetCoreOData-main-Yaml-release?branchName=main)](https://dev.azure.com/dotnet/OData/_apis/build/status/AspNetCoreOData/AspNetCoreOData-main-Yaml-release?branchName=main)
 
-## 1. Introduction
+## 1. Basic Usage
 
-**Be noted**:  Switch to use "main" as default branch. 1/6/2022
+### Microsoft.AspNetCore.OData Package Installation
+Using .NET CLI:
+```bash
+dotnet add package Microsoft.AspNetCore.OData
+```
+
+Using Package Manager:
+```bash
+Install-Package Microsoft.AspNetCore.OData
+```
+
+### Getting Started
+
+#### Creating an OData Service
+
+Here's a simple example of how to create an OData service using `Microsoft.AspNetCore.OData`:
+
+**I. Create an ASP.NET Core Application**:
+- Open Visual Studio and create a new ASP.NET Core Web API project.
+
+**II. Add the `Microsoft.AspNetCore.OData` Package**:
+- Install the package using the instructions above.
+
+**III. Define Your Models**:
+- Create your data models. For example:
+  ```cs
+    namespace MyODataApp.Models
+    {
+        public class Product
+        {
+            public int Id { get; set; }
+            public string Name { get; set; }
+            public decimal Price { get; set; }
+        }
+    }
+  ```
+
+**IV. Add an OData Controller**:
+- Create a controller to handle OData requests:
+  ```cs
+    using Microsoft.AspNetCore.Mvc;
+    using Microsoft.AspNetCore.OData.Routing.Controllers;
+    using MyODataApp.Models;
+    using System.Collections.Generic;
+    using System.Linq;
+
+    namespace MyODataApp.Controllers
+    {
+        public class ProductsController : ODataController
+        {
+            private static List<Product> products = new List<Product>
+            {
+                new Product { Id = 1, Name = "Product 1", Price = 10.0M },
+                new Product { Id = 2, Name = "Product 2", Price = 20.0M }
+            };
+
+            [EnableQuery]
+            public IActionResult Get()
+            {
+                return Ok(products);
+            }
+
+            [EnableQuery]
+            public IActionResult Get(int key)
+            {
+                var product = products.FirstOrDefault(p => p.Id == key);
+                if (product == null)
+                {
+                    return NotFound();
+                }
+                return Ok(product);
+            }
+        }
+    }
+  ```
+
+**V. Configure OData in `Startup.cs`**:
+- Configure OData routes and services:
+
+- If you work with `Program.cs`, update as below. Refer to the [Getting Started Guide](https://learn.microsoft.com/odata/webapi-8/getting-started).
+
+  ```cs
+    // using statements
+    var builder = WebApplication.CreateBuilder(args);
+
+    var modelBuilder = new ODataConventionModelBuilder();
+    modelBuilder.EntityType<Order>();
+    modelBuilder.EntitySet<Customer>("Customers");
+
+    builder.Services.AddControllers().AddOData(
+        options => options.Select().Filter().OrderBy().Expand().Count().SetMaxTop(null).AddRouteComponents(
+            "odata",
+            GetEdmModel()));
+
+    var app = builder.Build();
+
+    // Send "~/$odata" to debug routing if enable the following middleware
+    // app.UseODataRouteDebug();
+    app.UseRouting();
+
+    app.MapControllers();
+
+    app.Run();
+
+    static IEdmModel GetEdmModel()
+    {
+        var builder = new ODataConventionModelBuilder();
+        builder.EntitySet<Product>("Products");
+        return builder.GetEdmModel();
+    }
+  ```
+
+  ```cs
+    using Microsoft.AspNetCore.Builder;
+    using Microsoft.AspNetCore.Hosting;
+    using Microsoft.Extensions.DependencyInjection;
+    using Microsoft.OData.Edm;
+    using Microsoft.OData.ModelBuilder;
+
+    namespace MyODataApp
+    {
+        public class Startup
+        {
+            public void ConfigureServices(IServiceCollection services)
+            {
+                services.AddControllers();
+                services.AddOData(opt => opt.AddModel("odata", GetEdmModel()).Filter().Select().Expand().OrderBy().Count().SetMaxTop(100));
+            }
+
+            public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+            {
+                // Send "~/$odata" to debug routing if enable the following middleware
+                // app.UseODataRouteDebug();
+                app.UseRouting();
+                app.UseEndpoints(endpoints =>
+                {
+                    endpoints.MapControllers();
+                    endpoints.Select().Expand().Filter().OrderBy().Count().MaxTop(100);
+                    endpoints.MapODataRoute("odata", "odata", GetEdmModel());
+                });
+            }
+
+            private static IEdmModel GetEdmModel()
+            {
+                var builder = new ODataConventionModelBuilder();
+                builder.EntitySet<Product>("Products");
+                return builder.GetEdmModel();
+            }
+        }
+    }
+  ```
+
+**VI. Run Your Application**:
+
+- Start your application and navigate to `/odata/Products` to see your OData service in action.
+
+
+**That's it.**
+
+## 2. Github Repository
 
 This is the official ASP.NET Core OData repository.
 [ASP.NET Core OData](https://www.nuget.org/packages/Microsoft.AspNetCore.OData/8.0.0) is a server side library built upon ODataLib and ASP.NET Core.
@@ -59,81 +218,6 @@ For comprehensive documentation, please refer to the following links:
 
    - Includes **Microsoft.AspNetCore.OData.NewtonsoftJson** project, Unit Test, E2E Test & Samples
 
-## 2. Basic Usage
-
-### Microsoft.AspNetCore.OData Package Installation
-Using .NET CLI:
-```bash
-dotnet add package Microsoft.AspNetCore.OData
-```
-
-Using Package Manager:
-```bash
-Install-Package Microsoft.AspNetCore.OData
-```
-
-In the ASP.NET Core Web Application project, update your `Startup.cs` as below:
-
-```C#
-public class Startup
-{
-    public void ConfigureServices(IServiceCollection services)
-    {
-        services.AddDbContext<BookStoreContext>(opt => opt.UseInMemoryDatabase("BookLists"));
-        services.AddControllers().AddOData(opt => opt.AddRouteComponents("odata", GetEdmModel()));
-    }
-
-    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
-    {
-        // Send "~/$odata" to debug routing if enable the following middleware
-        // app.UseODataRouteDebug();
-
-        app.UseRouting();
-        app.UseEndpoints(endpoints =>
-        {
-            endpoints.MapControllers();
-        });
-    }
-
-    private static IEdmModel GetEdmModel()
-    {
-        // …
-    }
-}
-```
-
-If you work with `Program.cs`, update as below. Refer to the [Getting Started Guide](https://learn.microsoft.com/odata/webapi-8/getting-started).
-```c#
-// using statements
-
-var builder = WebApplication.CreateBuilder(args);
-
-var modelBuilder = new ODataConventionModelBuilder();
-modelBuilder.EntityType<Order>();
-modelBuilder.EntitySet<Customer>("Customers");
-
-builder.Services.AddControllers().AddOData(
-    options => options.Select().Filter().OrderBy().Expand().Count().SetMaxTop(null).AddRouteComponents(
-        "odata",
-        GetEdmModel()));
-
-var app = builder.Build();
-
-app.UseRouting();
-
-app.MapControllers();
-
-app.Run();
-
-static IEdmModel GetEdmModel()
-{
-    // …
-}
-```
-
-That's it. 
-
-
 ## 3. Building, Testing, Debugging and Release
 
 ### 3.1 Building and Testing in Visual Studio

diff --git a/src/Microsoft.AspNetCore.OData.Nightly.nuspec b/src/Microsoft.AspNetCore.OData.Nightly.nuspec
@@ -13,6 +13,7 @@
     <license type="expression">MIT</license>
     <requireLicenseAcceptance>true</requireLicenseAcceptance>
     <tags>Microsoft AspNetCore WebApi OData</tags>
+    <readme>docs\README.md</readme>
     <icon>images\odata.png</icon>
     <repository type="git" url="https://github.com/OData/AspNetCoreOData.git" branch="master" />
     <dependencies>
@@ -29,5 +30,8 @@
     <file src="$ProductRoot$\net8.0\Microsoft.AspNetCore.OData.xml" target="lib\net8.0" />
     <file src="$ProductRoot$\net8.0\Microsoft.AspNetCore.OData.pdb" target="lib\net8.0" />
     <file src="$SourcesRoot$\images\odata.png" target="images\" />
+
+    <!-- readme file -->
+    <file src="$SourcesRoot$\README.md" target="docs\" />
   </files>
 </package>
diff --git a/src/Microsoft.AspNetCore.OData.Release.nuspec b/src/Microsoft.AspNetCore.OData.Release.nuspec
@@ -13,6 +13,7 @@
     <license type="expression">MIT</license>
     <requireLicenseAcceptance>true</requireLicenseAcceptance>
     <tags>Microsoft AspNetCore WebApi OData</tags>
+    <readme>docs\README.md</readme>
     <icon>images\odata.png</icon>
     <repository type="git" url="https://github.com/OData/AspNetCoreOData.git" branch="master" />
     <dependencies>
@@ -29,5 +30,8 @@
     <file src="$ProductRoot$\net8.0\Microsoft.AspNetCore.OData.xml" target="lib\net8.0" />
     <file src="$ProductRoot$\net8.0\Microsoft.AspNetCore.OData.pdb" target="lib\net8.0" />
     <file src="$SourcesRoot$\images\odata.png" target="images\" />
+
+    <!-- readme file -->
+    <file src="$SourcesRoot$\README.md" target="docs\" />
   </files>
 </package>
diff --git a/src/Microsoft.AspNetCore.OData/Microsoft.AspNetCore.OData.csproj b/src/Microsoft.AspNetCore.OData/Microsoft.AspNetCore.OData.csproj
@@ -4,7 +4,6 @@
     <TargetFramework>net8.0</TargetFramework>
     <RootNamespace>Microsoft.AspNetCore.OData</RootNamespace>
     <DocumentationFile>$(OutputPath)$(AssemblyName).xml</DocumentationFile>
-    <PackageReadmeFile>README.md</PackageReadmeFile>
     <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
     <!-- Let's generate our own assembly info -->
     <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
@@ -71,10 +70,6 @@
     <AdditionalFiles Include="PublicAPI.Unshipped.txt" />
   </ItemGroup>
 
-  <ItemGroup>
-    <None Include="README.md" Pack="true" PackagePath="\" />
-  </ItemGroup>
-
   <ItemGroup>
     <Service Include="{508349b6-6b84-4df5-91f0-309beebad82d}" />
   </ItemGroup>