Skip to content

Commit

Permalink
docs: update README with the new example
Browse files Browse the repository at this point in the history 
Signed-off-by: Andrew Berezovskyi <[email protected]>
  • Loading branch information
@berezovskyi
berezovskyi committed Oct 19, 2024
1 parent f30ad7e commit 61f83b4
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 41 deletions.
22 changes: 22 additions & 0 deletions OSLC4Net_NETFramework/OSLC4Net.StockQuoteSample/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
### Running the sample StockQuote provider

> [!NOTE]
> Sample StockQuote provider has not yet been migrated to .NET 6+.
> [!WARNING]
> Sample StockQuote provider is a toy implementation and does not correspond to any [standards-track OSLC specifications](https://open-services.net/specifications/).
`OSLC4Net.StockQuoteSample` is a sample OSLC provider which implements one resource type, a StockQuote. This resource is not defined by an OSLC specification, it shows how OSLC4Net can be used to create an experimental OSLC provider.

1. Build the `OSLC4Net_SDK\OSLC4Net.Core.sln` solution
1. Right click the `OSLC4Net.StockQuoteSample` project and run it via _Debug->Start new instance_

You'll see a web page created - that is currently just a skeleton provided by ASP.NET. Try performing a GET request using [Postman](https://www.postman.com/) (make sure to set the `Accept` header to `application/rdf+xml`:

* http://localhost:7077/api/stockquote - returns all StockQuotes
* http://localhost:7077/api/stockquote?getShape=true - returns the StockQuote OSLC resource shape
* http://localhost:7077/api/stockquote/nasdaq_goog - returns an individual StockQuote

A request to the first URL using Fiddler should have the following response:

![](https://raw.githubusercontent.com/OSLC/oslc4net/master/doc/stockquote.png)
91 changes: 50 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,66 +6,75 @@

## What is OSLC4NET?

**OSLC4Net** is an SDK and sample applications that help the .NET community adopt Open Services for Lifecycle Collaboration (OSLC, [homepage](http://open-services.net)) and build OSLC-conformant tools.

The SDK allows developers to create OSLC servers and clients by adding OSLC annotations to .NET objects to represent them as OSLC resources. It includes a library based on the [dotNetRDF](https://dotnetrdf.org/) package, which assists with representing these resources as RDF and helps parse Turle, RDF/XML, and JSON-LD documents into OSLC .NET objects.

The [OSLC4Net.Client package](https://www.nuget.org/packages/OSLC4Net.Client/) can be used to help create consumer REST requests. On the server side, the project offers an RDF-specific `MediaTypeFormatter` that can help process OSLC REST requests within an ASP.NET MVC 5 API. **Join the [discussion on the .NET Core migration](https://github.com/OSLC/oslc4net/issues/25).**
**OSLC4Net** is an SDK and sample applications that help the .NET community
adopt Open Services for Lifecycle Collaboration (OSLC,
[homepage](http://open-services.net)) and build OSLC-conformant tools.

The SDK allows developers to create OSLC servers and clients by adding OSLC
annotations to .NET objects to represent them as OSLC resources. It includes a
library based on the [dotNetRDF](https://dotnetrdf.org/) package, which assists
with representing these resources as RDF and helps parse Turle, RDF/XML, and
JSON-LD documents into OSLC .NET objects.

The [OSLC4Net.Client package](https://www.nuget.org/packages/OSLC4Net.Client/)
can be used to help create consumer REST requests. On the server side, the
project offers an RDF-specific `MediaTypeFormatter` that can help process OSLC
REST requests within an ASP.NET MVC 5 API. **Join the [discussion on the .NET
Core migration](https://github.com/OSLC/oslc4net/issues/25).**

## Getting started

If you do not have a .NET development environment, start by downloading VS Code [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit). Make sure to install .NET 8 SDK for development. Libraries target NETStandard 2.0 and should run on .NET Framework 4.8 or .NET 6+ (recommended).
If you do not have a .NET development environment, start by downloading VS Code
[C# Dev
Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit).
Make sure to install .NET 8 SDK for development. Libraries target NETStandard
2.0 and should run on .NET Framework 4.8 or .NET 6+ (recommended).

### A simple OSLC Client

Create a new console application targeting .NET 6+, add a NuGet dependency to `OSLC4Net.Client` (make sure the *Include prerelease* is checked if you see an empty list) and add the following code:
Create a new console application targeting .NET 6+, add a NuGet dependency to
`OSLC4Net.Client` (make sure the *Include prerelease* is checked if you see an
empty list) and add the following code:

```csharp
private const string OSLC_SERVER_URI = "https://oslc.itm.kth.se/ccm";
var oslcClient = OslcClient.ForBasicAuth(username, password);

static void Main(string[] args)
var resourceUri =
"https://jazz.net/sandbox01-ccm/resource/itemName/com.ibm.team.workitem.WorkItem/1300";
OslcResponse<ChangeRequest> response = await oslcClient.GetResourceAsync<ChangeRequest>(resourceUri);
if (response.Resource is not null)
{
try
{
var helper = new JazzRootServicesHelper(OSLC_SERVER_URI, OSLCConstants.OSLC_CM_V2);
var catUri = helper.GetCatalogUrl();
Console.WriteLine($"The OSLC server has an OSLC Service Provider Catalog at the following URI:\n {catUri}");
} catch (RootServicesException e) {
Console.WriteLine($"Failed to fetch the OSLC RootServices document from:\n {OSLC_SERVER_URI}/rootservices");
}
Console.ReadLine();
ChangeRequest wi1300 = response.Resource;
logger.LogInformation($"{wi1300.GetShortTitle()} {wi1300.GetTitle()}");
}
else
{
logger.LogError("Something went wrong: {} {}", (response.StatusCode as int?) ?? -1,
response.ResponseMessage?.ReasonPhrase);
}
```

This should give you a valid response.

### Running the sample StockQuote provider

> [!NOTE]
> Sample StockQuote provider has not yet been migrated to .NET 6+.
> [!WARNING]
> Sample StockQuote provider is a toy implementation and does not correspond to any [standards-track OSLC specifications](https://open-services.net/specifications/).
`OSLC4Net.StockQuoteSample` is a sample OSLC provider which implements one resource type, a StockQuote. This resource is not defined by an OSLC specification, it shows how OSLC4Net can be used to create an experimental OSLC provider.

1. Build the `OSLC4Net_SDK\OSLC4Net.Core.sln` solution
1. Right click the `OSLC4Net.StockQuoteSample` project and run it via _Debug->Start new instance_
```

You'll see a web page created - that is currently just a skeleton provided by ASP.NET. Try performing a GET request using [Postman](https://www.postman.com/) (make sure to set the `Accept` header to `application/rdf+xml`:
Replace `resourceUri` with a valid OSLC resource URI. This should give you a
valid response. See [full example
project](./OSLC4Net_SDK/Examples/Oslc4NetExamples.Client/) for more details.

* http://localhost:7077/api/stockquote - returns all StockQuotes
* http://localhost:7077/api/stockquote?getShape=true - returns the StockQuote OSLC resource shape
* http://localhost:7077/api/stockquote/nasdaq_goog - returns an individual StockQuote
> [!TIP]
>
> Use https://github.com/oslc-op/refimpl to quickly run a few conformant OSLC
> servers.
A request to the first URL using Fiddler should have the following response:
## OSLC Server support

![](https://raw.githubusercontent.com/OSLC/oslc4net/master/doc/stockquote.png)
Server parts of the SDK have not yet been migrated from .NET Framework to .NET
8+.

## More information on OSLC

* See the [OSLC](http://open-services.net/) site for more details on OSLC specifications and community activities.
* See the [Eclipse Lyo](http://eclipse.org/lyo) site for information on OSLC SDKs and samples for other technologies.
* See the [OSLC](http://open-services.net/) site for more details on OSLC
specifications and community activities.
* See the [Eclipse Lyo](http://eclipse.org/lyo) site for information on OSLC
SDKs and samples for other technologies.

## OSLC4Net License

Expand Down

0 comments on commit 61f83b4

Please sign in to comment.