When migrating existing business services to Azure PaaS as part of an App Modernization project, you may find yourself seriously considering serverless computing using Azure Functions, especially if your target architecture includes MicroServices.

Azure Functions let you focus on what counts — your requirements, your time, and your code — and less about boilerplate code, infrastructure, and processes.

When creating new APIs in any technology, one thing is very important: Documenting those APIs so that others can use them. This is especially important in large enterprises or situations where you are exposing these APIs to the public.

This blog series guides you through creating a C# Function App, creating self-documenting APIs, ensuring the quality of that generated documentation, and separating documentation based on the audience.

The blog series assumes the following:

  • You are familiar with C#.
  • You have knowledge of software development fundamentals.
  • You are comfortable with command-line interfaces.

At AIS, we’ve determined that one of the best approaches to documenting your APIs is to use OpenAPI (formerly Swagger) to have the APIs (nearly) document themselves. This saves time in the long run and even enables API clients to automatically generate client code to interact with your APIs. This helps with shelf life – if 6 months or a year down the road, we decide a better approach is best.

For these articles, I will walk you through the steps for creating well-documented Azure Functions for our fictitious shopping site called “Bmazon” and its modernization effort.

Creating the App

To create the app, we will start with the Azure Functions Core Tools. At the time of this writing, the current version of this library is 3.0.3477

NOTE: This version uses dotnet cli version 3.1 internally, so if your dotnet executable in the path is not that version, it could cause you issues. If you run into errors, this may be fixed by adding global.json file in the current directory with the following content, which will tell the dotnet cli to use whatever 3.1.x version you have installed.

{
  "sdk": {
    "version": "3.1.0",
    "rollForward": "latestMinor"
  }
}

At the PowerShell prompt, we’ll run the following to create our project

C:\dev> func --version
3.0.3477
C:\dev> func init Bmazon --worker-runtime dotnet

Writing C:\dev\Bmazon\.vscode\extensions.json

This will create the shell of a project inside the C:\dev\Bmazon folder.

While creating the app, I’ve copied in an OrderService and the related DTOs from the existing application we’re modernizing to be used by the newly new functions we are creating. You can see the completed code on GitHub. You’ll see a bit more of them in the next article.

Learn more about Azure Functions From Microsoft Docs

Add Functions

We’re going to add 3 different functions to our app.

Shopping API

The Shopping division needs to call HTTP APIs to make an order to the warehouse, so we will add a CreateOrder function that performs this action.

(This can be done interactively by running func new and following prompts, but using the command line parameters is more concise.)

C:\dev\Bmazon> func new --template HttpTrigger --name CreateOrder `
    --authlevel Anonymous
Use the up/down arrow keys to select a template:Function name: CreateOrder

The function "CreateOrder" was created successfully from the 
"HTTPTrigger" template.

Strangely, it outputs a prompt to select the template even when you have passed in the selection as a parameter. You can ignore this.

Warehouse API

Later in our process, the Warehouse team needs to call an HTTP endpoint to send tracking information back to the Shopping division.

We will follow the pattern above and create an API for them to call.

C:\dev\Bmazon> func new --template HTTPTrigger --name OrderShipped `
    --authlevel Anonymous
Use the up/down arrow keys to select a template:Function name: OrderShipped

The function "OrderShipped" was created successfully from the 
"HTTPTrigger" template.

Shared APIs

Since both the Shopping and Warehouse divisions will need to check on the status of an order at various times, there will be a shared function to check status.

C:\dev\Bmazon> func new --template HTTPTrigger --name OrderShippingStatus `
    --authlevel Anonymous
Use the up/down arrow keys to select a template:Function name: OrderShipped

The function "OrderShippingStatus" was created successfully from the 
"HTTPTrigger" template.

Code Cleanup

We’ll do a bit of code cleanup before moving on.

Choose GET or POST

If you look at the code, you’ll notice that, by default, the Functions were created supporting both GET and POST.

public async Task<IActionResult> Run(
   [HttpTrigger(AuthorizationLevel.Anonymous, &quot;get&quot;, &quot;post&quot;, Route = null)]
   HttpRequest req
...

We can fix that by changing the code on each function by removing either "get" or "post" appropriately (Typically you will have the first 2 operations be POSTs and the latter be GET).

Organizing the Code

The func calls above will create all the Function files in the top folder. We’ll move ours into a Functions folder to keep things cleaner. They all just happened to start with “O”, so we can be terse.

C:\dev\Bmazon&gt; mkdir Functions; mv O*.cs Functions\

Add OpenAPI Document Generation

In order to add OpenAPI to Azure Functions, I chose to use the Swashbuckle library. There are a few other libraries out there to work with .Net and OpenAPI, but I chose Swashbuckle because I’m familiar with it.

Installing the Package

The core Swashbuckle project doesn’t support Azure Functions directly, so I used the AzureExtensions.Swashbuckle package, a nice extension written by Vitaly Bibikov.

To install it:

C:\dev\Bmazon&gt; dotnet add package AzureExtensions.Swashbuckle

  Determining projects to restore...
  Writing C:\Users\XXX\AppData\Local\Temp\tmp69AA.tmp
info : Adding PackageReference for package 'AzureExtensions.Swashbuckle' into project 'C:\dev\Bmazon\Bmazon.csproj'.
info : Restoring packages for C:\dev\Bmazon\Bmazon.csproj...
...
...
info : Committing restore...
info : Generating MSBuild file C:\dev\Bmazon\obj\Bmazon.csproj.nuget.g.props.
info : Writing assets file to disk. Path: C:\dev\Bmazon\obj\project.assets.json
log  : Restored C:\dev\Bmazon\Bmazon.csproj (in 525 ms).

Setting up Swashbuckle

In order to configure Swashbuckle, your Functions App needs a Functions Startup class like the following, which we’ll put in Startup.cs in the Bmazon folder.

using System.Reflection;
using AzureFunctions.Extensions.Swashbuckle;
using Microsoft.Azure.Functions.Extensions.DependencyInjection;

[assembly: FunctionsStartup(typeof(Bmazon.Startup))]
namespace Bmazon
{
  public class Startup : FunctionsStartup
  {
    public override void Configure(IFunctionsHostBuilder builder)
    {
      builder.AddSwashBuckle(Assembly.GetExecutingAssembly());
    }
  }
}

Exposing OpenAPI Endpoints

Your code will also need to expose the OpenAPI JSON and UI endpoints as HTTP-triggered Azure Functions so that client code can load them on demand.

(Adding them in a single OpenApi\OpenApiFunctions.cs file for now)

using System.Net.Http;
using System.Threading.Tasks;
using AzureFunctions.Extensions.Swashbuckle;
using AzureFunctions.Extensions.Swashbuckle.Attribute;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;

namespace Bmazon.OpenApi
{
  public static class OpenApiFunctions
  {
    [SwaggerIgnore]
    [FunctionName(&quot;OpenApiJson&quot;)]
    public static Task&lt;HttpResponseMessage&gt; RunJson(
        [HttpTrigger(
            AuthorizationLevel.Anonymous, 
            &quot;get&quot;, Route = &quot;openapi/json&quot;)]
        HttpRequestMessage req,
        [SwashBuckleClient] ISwashBuckleClient swashbuckleClient)
    {
      return Task.FromResult(
            swashbuckleClient.CreateSwaggerJsonDocumentResponse(req));
    }

    [SwaggerIgnore]
    [FunctionName(&quot;OpenApiUI&quot;)]
    public static Task&lt;HttpResponseMessage&gt; RunUi(
        [HttpTrigger(
            AuthorizationLevel.Anonymous, 
            &quot;get&quot;, 
            Route = &quot;openapi/ui&quot;)]
        HttpRequestMessage req,
        [SwashBuckleClient] ISwashBuckleClient swashbuckleClient)
    {
      // CreateOpenApiUIResponse generates the HTML page from the JSON results
      return Task.FromResult(
            swashbuckleClient.CreateSwaggerUIResponse(req, &quot;openapi/json&quot;));
    }
  }
}

This sets up 2 new Functions on the openapi/json and openapi/ui URLs to load the JSON file and Swagger UI respectively. The [SwaggerIgnore] attribute causes Swashbuckle to ignore these API methods for document generation purposes.

Generate and View the API Documentation

NOTE: You must have the Azure Storage Emulator or Azurite RUNNING locally in order for this to work properly.

C:\dev\Bmazon&gt; func start
Microsoft (R) Build Engine version 16.8.3+39993bd9d for .NET
Copyright (C) Microsoft Corporation. All rights reserved.

  Determining projects to restore...
  Restored C:\dev\Bmazon\Bmazon.csproj (in 840 ms).
  Bmazon -&gt; C:\dev\Bmazon\bin\output\bin\Bmazon.dll

Build succeeded.

Time Elapsed 00:00:05.60

Azure Functions Core Tools
Core Tools Version:       3.0.3284 Commit hash: 98bc25e668274edd175a1647fe5a9bc4ffb6887d
Function Runtime Version: 3.0.15371.0

[2021-02-27T15:05:33.871Z] Found C:\dev\Bmazon\Bmazon.csproj. Using for user secrets file configuration.

Functions:

  CreateOrder: [POST] http://localhost:7071/api/order
  OpenApiJson: [GET] http://localhost:7071/api/openapi/json
  OpenApiUi: [GET] http://localhost:7071/api/openapi/ui
  OrderShipped: [POST] http://localhost:7071/api/order/shipment
  OrderShippingStatus: [GET] http://localhost:7071/api/order/shipment/{id}

For detailed output, run func with --verbose flag.
[2021-02-27T15:05:41.693Z] Host lock lease acquired by instance ID '000000000000000000000000016514FF'.

If you don’t see that last line after a few seconds, you probably don’t have the storage emulator running

Take note of the list of functions shown with the URLs next to them, especially the ones starting with “OpenApi”.

If you visit the OpenApiUI URL listed above, you will see the following in your browser:

Rendered Swagger UI displaying the 3 created Operations

That’s it! You now have a modernized serverless architecture with APIs that are documenting themselves!

If you add any new Functions, they will automatically show up here as well. Your clients can download from the JSON endpoint and import the definitions into Postman or client generators.

Get the completed code from GitHub

Next Steps

Now that you have self-documenting APIs, you may notice that the information in the Swagger UI is rather underwhelming. Due to the nature of Azure Functions, there is very little information that Swagger can glean from the runtime type information it can gather.

In part two of the series, I will show you how to make the documentation MUCH better.

TOP MODERNIZATION APPROACHES
Learn about the top three modernization approaches — rehosting, replatforming, and refactoring — uncovering pros, cons, and process ideas as you go.

For those who are familiar with Microsoft’s popular Dashboard in a Day workshops for Power BI, App in a Day (AIAD) is very similar. The program is an all-day training designed to accelerate attendees’ Power Apps, Microsoft Flow, and CDS for Apps experience. The comprehensive hands-on workshop is led by a certified Microsoft Partner, in this case, your friends at Applied Information Sciences.

The training provides practical experience in a full-day of instructor lead App creation workshops. You learn how to build custom apps that run on mobile devices with which you can share inside your organization securely.

Inside the AIAD Workshop

Full house at the AIAD at Microsoft’s Reston MTC

Trainees at App in a Day

Read More…

Yesterday AIS’ VP of Business Development Larry Katzman sat down with Federal Tech Talk’s John Gilroy on Federal News Radio to discuss how federal IT professionals can innovate in a constantly changing environment..and with a shrinking budget.

The discussion starts off with a common theme — today’s younger generation is accustomed to programming from an early age.  When they show up for work at an agency, the expect to be able to “fire up” environments to test code.

Everyone wants to unlock this spirit of innovation – but there are certain restraints. For example, you may use a system that only needs a credit card to get started.  This can result in “drunken sailor syndrome.”  In other words, you may blow your annual budget in the first week if you are not careful.

From there, the conversation moves into the issue of “Rogue IT” or “Shadow IT,” where users sign up for cloud offerings on their own and completely bypass the CIO. AIS actually offers a solution to this one: CloudCap, a system where users are granted access to thousands of enterprise class applications that can be managed. Much like “managed services,” the CloudCap system allows both the user and supervisor to know how much is spent and when.

For more information about CloudCap, click here.

You can listen to the full interview over at Federal News Radio.

 

22106868_sYou’re an enterprise. You’ve done your research. You’ve read the whitepapers. You’ve heard all the success stories (along with a few cautionary tales). Perhaps you’ve already taken your first steps into the cloud, but want to embark on a larger-scale public cloud adoption strategy.

But what does that look like for your enterprise? The journey is different for you – for everyone, really. And you certainly don’t want to make it up as you go along.

Here are five important things you need to map out before you start your public cloud journey. We’re confident in this roadmap because we’ve been along for the ride before. We’ve helped many large enterprises and agencies successfully adopt and implement their own unique cloud strategies. Read More…

WindowsAzureAs more and more businesses move their applications to the cloud, it’s clear that operation and log data analysis is a major component to the migrating process. That data is crucial to understanding the health and reliability of your cloud services with respect to scalability, resilience, uptime, and your ability to troubleshoot issues.

But how do you deal with all that operational data? How do you identify specific application issues such as exceptions raised from bugs in the code, troubling increases in processor or memory consumption, or slow response times?

It turns out that migrating your applications to the cloud is just the first step: Having a well-thought-out operational data and monitoring user story is just as important. Read More…

Cloud ComputingA few weeks ago, AIS’ Solutions Architect, Jason McNutt and Managing Director, Larry
Katzman spoke with Federal Tech Talk’s John Gilroy on Federal News Radio for a discussion around federal agencies moving to the cloud and to answer the question of “what happens once you get there?”

Listen to the interview.

John Gilroy states that “This is a critical question ask in the brave new world of the cloud. No human can conceivably be able to understand all the dependencies and updates that are needed for a complex cloud migration. This ability to manage the system is just as important once it is live. Jason McNutt talks about the capability of automation to be able to manage today’s complex systems.”

Federal Tech Talk looks at the world of high technology in the federal government. Host John Gilroy of The Oakmont Group speaks the language of federal CISOs, CIOs and CTOs, and gets into the specifics for government IT systems integrators. John covers the latest government initiatives and technology news for the federal IT manager and government contractor. Follow John on Twitter @raygilrar and hear more from Federal Talk Talk on federalnewsradio.com

Listen to the interview.

In Part 1 of this blog series, we outlined the case for a Service Catalog driven approach for Enterprise DevOps. At AIS, after having worked with several of our Enterprise clients with their DevOps journey, we harvested our learnings in the form of a fully managed service catalog – AIS Service Catalog. AIS Service Catalog is a Microsoft Azure focused SaaS offering that is designed to jumpstart your DevOps efforts by bringing you the benefits of the service catalog driven approach.

ASC

A Service Catalog for Microsoft Azure

In Part 1 of this blog post series, we identified four key features of a Service Catalog that are fundamental to establishing DevOps in an enterprise. Let us briefly talk about how AIS Service Catalog realizes these features using Microsoft Azure specific building blocks. Read More…

Microsoft Cloud ShowRecently, AIS’s Scott Hoag (@ciphertxt) joined Andrew Connell (@andrewconnell) and Chris Johnson (@loungeflyz) of the Microsoft Cloud Show to discuss Azure Application Proxy & Gateways. Topics covered in this podcast discussion include:

  • Using Application Proxy to publish applications for secure remote access
  • Enable Application Proxy services
  • Azure AD Application Proxy and SharePoint 2013
  • SSO for On Prem IWA Apps Using KCD with Application Proxy
  • Azure Application Gateway Pricing
  • What is Application Gateway
  • Azure Service Updates [RSS]

The Microsoft Cloud Show, is the only place to stay up to date on everything going on in the Microsoft cloud world including Azure and Office 365.

Click here to listen to this podcast.

AIS is proud to announce the release of our Chief Technology Officer Vishwas Lele’s Pluralsight course on Cloud Oriented Programming. This course demonstrates coding techniques to optimize your applications that are targeted to run in the public cloud.

The public cloud is tomorrow’s IT backbone. As cloud vendors introduce new capabilities, the application-building process is undergoing a profound transformation. The cloud is based on key tenets such as global scale, commodity hardware, usage-based billing, scale-out, and automation. But how does the cloud impact what we do as programmers every day? What do we need to do at a program level that aligns us with the aforementioned tenets? This course discusses 9 techniques / tips (organized in three modules) designed to help developers make more effective use of the cloud.

Click here to get started!

Read More…

MicrosoftAzure

Join Microsoft and AIS to learn how Azure Government Cloud can help Justice & Public Safety officials quickly respond to events at scale as needed.
 


The cloud platform designed to meet U.S. government demands Azure Government delivers cloud speed, scale, and economics while addressing the security and compliance needs of U.S. federal agencies including the Department of Defense, plus state and local governments and their solution providers. Azure Government offers physical and network isolation from non-U.S. government deployments and requires specialized personnel screening. Azure Government will address government regulatory and compliance requirements such as FedRAMP, CJIS, and HIPAA.

When local, state or federal authorities respond to criminal acts, they seek to quickly collect vast amount of inputs from the public.  This input can be in the form of tips, photos, videos or any untold observations.  Agencies need the capability to surge their IT tools and applications to collect the data, store it, and run big data analysis tools against the collected content to harvest information.

Register now for an exclusive Microsoft & AIS webinar to learn how you can:

  • Through a few clicks publish internet or extranet facing web or SharePoint site to organize with first responders to an incident or catastrophe
  • Provide a cost effective approach to development on larger scale environments
  • Extend the On-Prem footprint without exposing critical data
  • Reduce the burden of implementing back-up and disaster recovery for your applications.

RSVP TODAY!