From 3c4131111e924db3124f0d739a0677ea1ac3966c Mon Sep 17 00:00:00 2001 From: John Gathogo Date: Tue, 24 Oct 2023 20:38:45 +0300 Subject: [PATCH] Set schema for out-of-line annotations (#309) --- Odata-docs/TOC.yml | 2 + .../odatalib/v7/edm/set-annotations-schema.md | 190 ++++++++++++++++++ 2 files changed, 192 insertions(+) create mode 100644 Odata-docs/odatalib/v7/edm/set-annotations-schema.md diff --git a/Odata-docs/TOC.yml b/Odata-docs/TOC.yml index 7a18ff43..5bd50928 100644 --- a/Odata-docs/TOC.yml +++ b/Odata-docs/TOC.yml @@ -332,6 +332,8 @@ href: /odata/odatalib/navigation-partner - name: Optional parameters href: /odata/odatalib/optional-parameters + - name: Set schema for out-of-line annotations + href: /odata/odatalib/edm/set-annotations-schema - name: Batching items: - name: Batching requests diff --git a/Odata-docs/odatalib/v7/edm/set-annotations-schema.md b/Odata-docs/odatalib/v7/edm/set-annotations-schema.md new file mode 100644 index 00000000..80be7f98 --- /dev/null +++ b/Odata-docs/odatalib/v7/edm/set-annotations-schema.md @@ -0,0 +1,190 @@ +--- +title: "Set schema for out-of-line annotations" +description: "Set schema for out-of-line annotations" +author: gathogojr +ms.author: jogathog +ms.date: 10/9/2023 +ms.topic: article + +--- +# Set schema for out-of-line annotations +**Applies To**: [!INCLUDE[appliesto-odataclient](../../../includes/appliesto-odatalib-v7.md)] + +The Edm library lets you [define annotations](/odata/odatalib/edm/define-annotations). Annotations are used to define additional characteristics or capabilities of model elements. They can be expressed in the schema document in two ways: **inline** as child elements of the annotated element, or **out-of-line**/**externally** as children of an `Annotations` element that targets the model element to be annotated using a path expression that uniquely identifies the target model element. + +This page shows how to define an out-of-line annotation in a simple Edm model and specify the schema it should appear in. + +## Create an ASP.NET Core application +Create an ASP.NET Core application based on the ASP.NET Core Empty template and import the `Microsoft.AspNetCore.OData` nuget package: + +--- + +# [Visual Studio](#tab/visual-studio) + +In the Visual Studio **Package Manager Console**: +```powershell +Install-Package Microsoft.AspNetCore.OData +``` + +# [.NET Core CLI](#tab/netcore-cli) + +```dotnetcli +dotnet add package Microsoft.AspNetCore.OData +``` + +--- + +## Configure the OData service and build the Edm model +Replace the contents of _Program.cs_ file with the following code: + +```csharp +using Microsoft.AspNetCore.OData; +using Microsoft.OData.Edm; +using Microsoft.OData.Edm.Vocabularies; + +var builder = WebApplication.CreateBuilder(args); + +var model = new EdmModel(); + +// Add Employee entity to Ns namespace +var employeeEntityType = new EdmEntityType("Ns", "Employee"); +employeeEntityType.AddKeys( + employeeEntityType.AddStructuralProperty("Id", EdmPrimitiveTypeKind.Int32, isNullable: false)); +employeeEntityType.AddStructuralProperty("Name", EdmPrimitiveTypeKind.String, isNullable: true); +employeeEntityType.AddStructuralProperty("Salary", EdmPrimitiveTypeKind.Decimal, isNullable: false); +model.AddElement(employeeEntityType); + +// Add Entity Container to Default namespace +var defaultEntityContainer = new EdmEntityContainer("Default", "Container"); +model.AddElement(defaultEntityContainer); + +// Add Employee entity set to the entity container +var employeesEntitySet = defaultEntityContainer.AddEntitySet("Employees", employeeEntityType); + +// Add out-of-line vocabulary annotation +var notSortableVocabularyAnnotation = new EdmVocabularyAnnotation( + employeesEntitySet, + new EdmTerm("Org.OData.Capabilities.V1", "SortRestrictions", new EdmEntityTypeReference(employeeEntityType, isNullable: false)), + new EdmRecordExpression( + new EdmPropertyConstructor("Sortable", new EdmBooleanConstant(true)), + new EdmPropertyConstructor("AscendingOnlyProperties", new EdmCollectionExpression()), + new EdmPropertyConstructor("DescendingOnlyProperties", new EdmCollectionExpression()), + new EdmPropertyConstructor("NonSortableProperties", new EdmCollectionExpression( + new EdmPropertyPathExpression("Salary"))))); +model.AddVocabularyAnnotation(notSortableVocabularyAnnotation); + +// Configure OData service +builder.Services.AddControllers().AddOData( + options => options.AddRouteComponents( + model)); + +var app = builder.Build(); + +app.UseRouting(); +app.UseEndpoints(endpoints => endpoints.MapControllers()); + +app.Run(); +``` + +## Run the service +Run the application and query the service metadata: +```http +GET http://localhost:5000/$metadata +``` + +Response: +```xml + + + + + + + + + + + + + + + + + + + + + + + + + Salary + + + + + + + + + + + + + +``` + +The `Org.OData.Capabilities.V1.SortRestrictions` annotation appears under an `Annotations` element in the `Ns` namespace. + +## Set the schema the annotation should appear in +The following two steps show how to specify the schema the annotation should appear in: +1. Import `Microsoft.OData.Edm.Csdl` namespace. +2. Use the `SetSchemaNamespace` to set the schema namespace: + ```csharp + // ... rest of the Edm model definition code + model.AddVocabularyAnnotation(notSortableVocabularyAnnotation); + notSortableVocabularyAnnotation.SetSchemaNamespace(model, "Default"); + ``` + +## Rerun the service +Rerun the application and query the service metadata. This time round the `Annotations` element is in the `Default` namespace: +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Salary + + + + + + + + +``` \ No newline at end of file